README.md

4장 주석

주석은 코드로 의도를 표현하는 것에 실패했을 때 만회하기 위해 사용한다. 현실적으로 주석은 유지보수가 불가능하기 때문에 오래될수록 코드에 멀어지고, 완전히 그릇될 가능성도 커진다. 따라서 주석은 가능한 줄이도록 꾸준히 노력해야 한다.

주석은 언제나 실패를 의미한다
- 68p -

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

• 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.

코드로 의도를 표현하라

• 코드만으로 의도를 설명하기 어려운 경우가 존재하지만, 코드가 훌륭한 수단이 아니라는 의미는 아니다.
• 코드는 대다수의 의도를 표현할 수 있고, 주석으로 달려는 설명은 보통 함수로 만들어 표현해도 충분하다.

좋은 주석

• 법적인 주석
  • 저작권 정보나 소유권 정보와 같이 법적인 이유로 들어가는 내용
  • 모든 조항과 조건을 나열하는 대신, 표준 라이선스나 외부 문서 참조를 이용해도 된다.
• 정보를 제공하는 주석
  • 함수의 반환값에 대한 구체적인 설명처럼 정보를 제공성 내용
  • 이런 경우에도 가능하면 함수 이름에 정보를 담는 편이 더 좋다.
• 의도를 설명하는 주석
  • 코드 저자의 결정에 대한 의도를 설명하는 내용
  • 저자의 의도에 대한 동의 여부와 무관하게 저자의 의도를 분명하게 알 수 있다.
• 의미를 명료하게 밝히는 주석
  • 모호한 인수나 반환값의 의미를 설명하는 내용
  • 보통 인수나 반환값 자체를 더 명확하게 만드는 편이 좋으나, 표준 라이브러리나 변경하지 못하는 코드에 속한다면 주석을 유용하게 쓸 수 있다.
  • 그릇된 주석이 될 가능성이 상당히 높으므로 더 나은 방법이 없는지 고민하고 각별히 주의해야 한다.
• 결과를 경고하는 주석
  • 다른 프로그래머에게 결과를 경고하는 내용(ex. 스레드에 안전하지 않으므로 각 인스턴스를 독립적으로 생성하세요)
• TODO 주석
  • 구현하지 않은 이유와 미래 모습을 설명하는 내용
  • 필요하지만 당장 구현하기 어려운 업무들을 기술하고, 더 좋은 네이밍을 부탁하거나 문제를 봐달라고 요청할 때도 사용 가능하다.
  • TODO 주석이 너무 많은 것은 바람직하지 않으므로 주기적으로 점검해 불필요한 구석은 제거한다.
• 중요성을 강조하는 주석
  • 대수롭지 않다고 여겨질 수 있는 무언가의 중요성을 강조하는 내용
• 공개 API 에서 Javadocs
  • Javadocs 역시 독자를 오도하거나, 잘못 위치할 가능성이 존재하므로 주의해야 한다.

나쁜 주석

• 주절거리는 주석
  • 독자가 이해가 안되어 다른 부분까지 뒤져야 하는, 제대로 소통하지 못하는 주석
  • 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달아야 한다.
• 같은 이야기를 중복하는 주석
• 오해할 여지가 있는 주석
• 의무적으로 다는 주석
  • 모든 변수에 주석을 달자 등과 같은 불필요한 규칙을 만들어 다는 주석
• 이력을 기록하는 주석
  • 이전에는 소스 코드 관리 시스템이 없었기에 바람직했으나, 이제는 혼란만 가중한다.
• 있으나 마나 한 주석
  • 너무 당연한 사실을 언급하는 주석
  • 이런 주석이 많아지면 개발자가 주석을 무시하는 습관에 빠질 수도 있다.
• 무서운 잡음
  • 저자가 충분한 주의를 기울이지 않아 독자가 얻거갈 이익이 없는 주석
• 함수나 변수로 표현할 수 있다면 주석을 달지 마라
• 위치를 표시하는 주석
  • 소스 파일에서의 특정 위치를 표시하려고 사용하는 주석 (ex.// Actions ///////////)
  • 위와 같은 배너 아래에 특정 기능을 모아둔 경우 유용한 경우도 있으나 일반적으로는 가독성만 낮춘다. 따라서 정말 필요할 떄만, 불필요한 잡음인 슬래시를 제거하여 사용해야 한다.
• 닫는 괄호에 다는 주석
• 공로를 돌리거나 저자를 표시하는 주석
  • 소스 코드 관리 시스템이 충분히 해당 사실을 알려준다.
• 주석으로 처리한 코드
  • 주석처리된 코드는 사람들이 지우길 꺼려 불필요한 코드가 쌓이게 한다.
  • 소스 코드 관리 시스템이 이전 코드를 기억하므로 주석 처리가 불필요하다.
• HTML 주석
• 전역 정보
  • 주석은 근처에 있는 코드만 기술해야 한다.
• 너무 많은 정보
• 모호한 관계
  • 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.
• 함수 헤더
  • 짧고 한 가지만 수행하는 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.
• 비공개 코드에서 Javadocs
• 예제