주석은 나쁜 코드를 보완하지 못한다.
나쁜 코드를 작성하고, 주석으로 이를 설명하는 것은 좋지 않은 방법이다. 나쁜 코드를 작성하고 주석을 작성하는 대신 나쁜 코드를 좋은 코드로 변경하자.
좋은 주석
- 법적인 주석
- 정보를 제공하는 주석
- 의도를 설명하는 주석
- 의미를 명료하게 밝히는 주석
- 결과를 경고하는 주석
- 중요성을 강조하는 주석
- 공개 API에서 Javadocs
나쁜 주석
- 주절거리는 주석
- 같은 이야기를 중복하는 주석
- 오해할 여지가 있는 주석
- 의무적으로 다는 주석
- 이력을 기록하는 주석
- 있으나 마나 한 주석
- 저자를 표시하는 주석
- 주석으로 처리한 코드
- 과거의 코드를 주석으로 처리하지 말고 삭제하자. 과거 코드는 버전 관리 도구에서 언제든 확인할 수 있다.
- 주석으로 처리하기보다 커밋 메시지를 더 명확하게 달자.
- 비공개 코드에서 Javadocs
주석은 꼭 필요한 경우에만 달아야 한다. 코드로 설명할 수 있다면 코드로 설명하는 것이 가장 좋다.
