[클린코드] 4장. 주석

4장. 주석

나쁜 코드에 주석을 달지 마라. 새로 짜라.

경솔하고 근거없는 주석은 코드를 이해하기 더 어렵게 만들지만, 잘 달린 주석을 그 어떤 정보보다 유용하다.

• 주석은 오래될수록 코드에서 멀어진다.
• 그 이유는 주석까지 유지보수하기란 현실적으로 불가능하다.
• 즉, 코드는 변화하지만 주석은 변화하는 코드를 따라가지 못한다.

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

코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다. 코드를 알아보기 힘드니 주석으로 대체하는 것이다.

코드로 의도를 표현하라

좋은 코드일수록 주석은 줄어든다.

좋은 주석

그렇다면 주석이 필요한 경우는 언제일까?

• 법적인 주석: ex) 저작권 정보 or 소유권 정보, 라이센스
• 정보를 제공하는 주석: 기본적인 정보를 주석으로 제공하면 펀리한 경우가 있는데 이 때도 사실 코드에서 드러내야 한다. 하지만 코드에서도 드러내기 힘들다면 주석을 사용하자.
• 의도를 설명하는 주석: 코드를 설명하는 주석을 작성하지 말고, 어떤 기능인지 명확한 의도를 밝히는 주석을 사용하라.
• 결과를 경고하는 주석: 어떤 warning 같은 경고 메시지를 주석으로 사용하는 경우도 있다.
• TODO 주석: 앞으로 할 일을 //TODO 주석으로 남겨두면 편하다.
• 중요성을 강조하는 주석
• 공개 API에서 Javadocs

나쁜 주석

• 앞서 좋은 주석에서 살펴보았듯이 명확한 의도대로 사용하지 않고, 코드를 설명하는 주석은 당연히 나쁜 주석이라 할 수 있다. 이유는 코드로 표현하지 못하니까 주석으로 주절주절 나열하는 것이다. 이러면 주석의 길이도 길어지고, 읽는 사람도 해석하기 피곤해진다.
• 코드에서도 중복된 코드는 좋지 않은데, 주석도 중복된 주석은 좋지 않다.
• 코드로 해석하지 못하면 주석을 논리적으로 작성해야 하는데 이는 협업하는 입장에서 오해할 여지가 있을 수 있다. 왜나하면 본인 기준으로 주석을 작성하기 때문이다. 그러면 결국 주석 리뷰까지 해야하는 것이다..
• 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 좋지 않다.
• 또한 수정할 때마다 수정 이력을 남기는 것도 좋지 않다. (얼마나 길어질까..)
• 간혹 프로젝트마다 주석으로 처리된 코드들을 보았다. 이는 아마도 기능을 수정하면서 혹시 필요할 수도 있으니까 주석처리 한 것이다. 하지만 이는 굉장히 좋지 않다. 과감히 삭제하자.

느낀 점

어떤 주석이 좋은 주석인지, 나쁜 주석인지 살펴보았다. 우리가 프로그램을 개발하면서 공통점은 코드도 그렇고, 주석도 그렇고 결국에 협업하는 과정에서 어떻게 하면 유지보수하기 깔끔해질까를 궁극적으로 고민한다. 왜냐하면 결국에는 개발은 혼자하는 경우가 단 1도 없기 때문이다. (만약 1인 개발자라면 결국 누군가에게는 물려주어야 하지 않을까?)

아무튼! 내가 좋게 생각했던 주석도 결국엔 협업에서는 나쁜 주석일 수 있다. 이것은 실무를 하면서 경험하고 고쳐나갈 수 있다. 그러니 내가 하는 것이 꼭 정답이 아니라는 고정관념을 깨고, 다른 사람들과 좋은 SW를 만들 수 있도록 고민하고 개발해나가면 성장해나가지 않을까 싶다.

따라서 내가 무조건 옳다는 고정관념을 깨기 위해 계속 스터디하고, 학습해나가야 한다. 그래야 성장할 수 있는 것 같다.

References

• 클린코드