소스코드 주석(comment)에 대한

그러나 주석은 소스 코드를 이해하기 어렵게 만들 수 있습니다.

예를 들어,

1. 코드의 의도가 명확하므로 주석이 다소 중복됩니다.

“XX 출력, XX 수신, XX 처리 및 응답” 등

2. 주석이 관리되지 않고 설명이 소스코드의 내용과 전혀 다른 경우입니다.

참 안타까운 사실인데 소스코드를 수정하는 사람이 댓글을 수정하지 않습니다.

댓글 내용은 함정이 될 수 있으므로 이러한 상황에 직면한 개발자에게 위협이 될 수 있습니다.

3. 코드의 동작을 설명하는 대신 왜 그렇게 작성되었는지에 대한 근거를 작성합니다.

예를 들어 “깨끗한 코드와 글로벌 관리를 위한 오픈 소스, 어쩌구 저쩌구… 그게 구현되는 방식입니다”와 함께 작성되었다고 가정해 보겠습니다.

허용 가능한 수준은 README 파일에 설명되어 있으며 아예 없는 것이 낫다고 생각합니다.

때때로 나는 “성능상의 이유로 어쩌구 저쩌구 XXX”와 같이 공동 작업자가 오해를 피하는 데 도움이되는 댓글이 꽤 좋은 방향이라고 생각합니다.

추가로 댓글에 날짜와 계정 이름을 적는 경우가 간혹 있습니다.

이것은 버전 제어가 없는 세상에서는 도움이 되었을 수 있지만 Git과 같은 버전 제어 도구가 어디에나 있는 세상에서는 도움이 될 수 있습니다.

사용자 및 소스 코드 수정 날짜는 각 커밋 로그에 기록되므로 더 이상 주석으로 작성할 필요가 없습니다.

반대로 도움이 될 만한 몇 가지만 적으면 최적화를 위한 수학 공식이나 가독성, TODO, FIXME로 논리가 줄어들고 마지막으로 경고가 표시됩니다.

결국 주석은 공동 작업에 중요하지만 사용자에게도 유용합니다.

내가 작성했다고 해서 모든 코드를 기억하고 빨리 이해할 수 있는 것은 아닙니다.