챕터 4. 주석

주석은 나쁜 코드를 보완하지 못한다.

우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다.
코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다. 모듈을 짜고 보니 짜임새가 엄앙이고 알아먹기 어렵다. 지저분한 모듈이라는 사실을 자각한다. 그래서 자신에게 이렇게 말한다. "이런! 주석을 달아야겠다!"

코드를 확인하다 보면은 지우지 못하는 주석이 한두 개씩 있다. 주석이 없어도 시간을 내어서 코드를 확인하면 코드를 파악할 수 있지만, 이 주석이 있으면 내가 나중에 코드의 기능을 빨리 파악할 수 있거나 다른 팀원이 볼 때 도움이 된다고 생각하기 때문이다.
책에서는 이럴때 주석을 다는 것이 아니라, 코드를 정리해야 한다고 말한다. 주석으로 인해 코드 파악이 빠르게 된다고 느낀다면, 그것을 그대로 코드에 적용하면 된다. 하지만 주석을 아예 안쓰는 것도 좋다고 할 수는 없기에 책은 좋은 주석에 대해서 설명을 해준다.

좋은 주석

• 의도를 설명하는 주석 - 때로는 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다.
• 의미를 명료하게 밝히는 주석 - 때때로 애매한 인수나 반환 값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워진다.
• TODO 주석 - 때로는 '앞으로 할 일'을 TODO주석으로 남겨두면 편리하다.

나쁜 주석

• 같은 이야기를 중복하는 주석 - 코드를 정당화하는 주석도 아니고, 의도나 근거를 설명하는 주석도 아니다.
• 의무적으로 다는 주석 - 모든 함수나 변수에 주석을 다는 규칙은 어리석기 그지없다.
• 주석으로 처리한 코드 - 주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다. 이유가 있어 남겨 놓았으리라고 지우면 안 된다고 생각한다. 그래서 쓸모없는 코드는 점차 쌓여간다.

4강 후기

4강을 읽고 나는 내 프로그램에 주석이 얼마나 있는지도 모른다는 것을 깨달았다. 모든 주석을 없애는 것은 현실적으로 힘든 영역이지만, 주석을 가능한한 최소로 유지해야한다는것은 동의한다. 어쨌든 주석 또한 문자이므로 함수의 크기를 늘리기 때문이다. 주석을 최대한 줄이려면 앞서 얘기했던 것처럼, 주석의 내용을 그대로 코드로 옮기면 된다. 쉽지는 않겠지만 우리는 주석을 가능한 줄이도록 꾸준히 노력해야한다.