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

• 브라이언w.커니핸, P.J플라우커

• 코드로 의도를 표현할 때마다 스스로를 칭찬한다.

• 주석을 달때마다 자신에게 표현력이 없다는 사실을 푸념해야 마땅하다.

• 코드를 깔끔하게 정리하고 애초에 주석이 필요없는 방향으로 에너를 쏟아라

• 간혹 필요하더라도 주석을 가능한 줄이도록 꾸준한 노력을 해야한다.

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

• 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
• 자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는 데 시간을 보내라!

코드로 의도를 표현하라

좋은 주석

정보를 제공하는 주석

의도를 설명하는 주석

의미를 명료하게 밝히는 주석

결과를 경고하는 주석

todo 주석

• 앞으로 할일 을 todo주석으로 남겨두면 편하다
• todo 주석은 프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무를 기술 한다.
  • 더 이상 필요없는 기능을 삭제하라는 알림
  • 누군가에게 문제를 봐달라는 요청
  • 더 좋은 이름을 떠올려달라는 부탁
  • 앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의 등에 유용하다

중요성을 강조하는 주석

공개 API에서 Javadocs

나쁜 주석

주절거리는 주석

같은 이야기를 중복하는 주석

오해할 여지가 있는 주석

의무적으로 다는 주석

이력을 기록하는 주석

있으나 마나 한 주석

무서운 잡음

함수나 변수로 표현할 수 있다면 주석을 달지 마라

위치를 표시하는 주석

닫는 괄호에 다는 주석

주석으로 처리한 코드

HTML 주석

전역 정보

너무 많은 정보

모호한 관계

함수 헤더

비공개 코드에서Javadocs