04. 주석

한마디

"나쁜 코드에 주석을 달지 마라. 새로 짜라."
- 브라이언 W. 커니핸, P.J. 플라우거

우리는 코드로 의도를 충분히 표현하지 못해서 주석을 사용한다.

주석은 거짓말을 한다.

• 프로그래머들이 주석을 유지보수하기 쉽지 않아 주석은 오래될수록 틀린 정보를 가질 가능성이 높다.
• 부정확한 주석은 더 이상 지킬 필요가 없는 규칙이나 지켜서는 안 되는 규칙을 명시한다.

코드만이 정확한 정보를 제공하는 유일한 출처다.

좋은 주석

• 저작권 정보와 소유권 정보 등의 법적인 주석
• 의도를 설명하는 주석
• 중요성을 강조하는 주석
• 결과를 경고하는 주석
• //TODO 주석
• Javadocs
• 책에는 안써있지만 개인적으로 사용하기 시작한 플랫폼의 버전이나 deprecated 등의 정보가 달려있을 때 유용했다.

나쁜 주석

• 독자와 제대로 소통하지 못하는 주석
• 오해의 여지가 있는 주석
• 코드를 설명하는 주석은 코드보다 더 많은 정보를 전달하지도 못하면서 독자가 함수를 대충 이해하고 넘어가게 만든다.
• 의무적으로 다는 주석. 모든 변수에 주석을 달아야한다는 규칙은 어리석다.
• 형상관리 시스템의 도입으로 필요없어진 주석 이런건 git에서 확인하자구..
  • 이력을 기록하는 주석
  • 저자를 표시하는 주석
  • 코드에 치는 주석
• 닫는 괄호에 다는 주석
• HTML 주석
• 전역 정보
  코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라.

"이런! 주석을 달아야겠다!" 아니다! 코드를 정리해야 한다!