주석

잘 달린 주석은 그 어떤 정보보다 유용하다. 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다. 오래되고 조작한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다.

우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다. 주석 없이는 표현할 방법을 찾지 못해 할 수 없이 주석을 사용한다. 코드로 의도를 표현할 때마다 스스로를 칭찬해준다. 주석을 달 때마다 자신에게 표현력이 없다는 사실을 푸념해야 마땅하다.

부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다.

진실은 한곳에만 존재한다. 바로 코드다. 코드만이 자기가 하는 일을 진실되게 말한다. 코드만이 정환한 정보를 제공하는 유일한 출처다. 그러므로 간혹 주석이 필요할지라도 주석을 가능한 줄이도록 꾸준히 노력해야 한다.

• 주석은 나쁜 코드를 보완하지 못한다
  • 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
  • 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
• 코드로 의도를 표현하라!
  • 많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.
• 좋은 주석
  • 법적인 주석
  • 정보를 제공하는 주석
  • 의도를 설명하는 주석
  • 의미를 명료하게 밝히는 주석
  • 결과를 경고하는 주석
  • TODO 주석
  • 중요성을 강조하는 주석
  • 공개 API에서 Javadocs
• 나쁜 주석
  • 주절거리는 주석
  • 같은 이야기를 중복하는 주석
  • 오해할 여지가 있는 주석
  • 의무적으로 다는 주석
  • 이력을 기록하는 주석
  • 있으나 마나 한 주석
  • 무서운 잡음
  • 위치를 표시하는 주석
  • 닫는 괄호에 다는 주석
  • 공로를 돌리거나 저자를 표시하는 주석
  • 주석으로 처리한 코드
  • HTML 주석
  • 전역 정보
  • 너무 많은 정보
  • 모호한 관계
  • 함수 헤더
  • 비공개 코드에서 Javadocs