주석은 나쁜 코드를 보완하지 못한다
- 좋은 코드는 주석이 있는 나쁜 코드보다 좋다.
- 주석으로 설명하는 대신, 좋은 코드로 개선하라.
코드로 의도를 표현하라
- 나쁜 예시 : if ((employee.flags & HOURLY_FLAG) && (employ.age > 65))
- 좋은 예시 : if (employee.isEligibleForFullBenefits())
좋은 주석
- 저작권 정보, 소유권 정보 주석
- 추상 메서드가 반환할 값과 같은 기본적인 정보를 제공하는 주석 (함수 이름에 정보를 담는 편이 더 좋다)
- 결정에 깔린 의도를 설명하는 주석 (72p)
- 의미를 명료하게 밝히는 주석 (인수나 반환값 자체를 명확하게 만들면 좋지만, 표준 라이브러리나 변경 못하는 코드라면 주석 사용)
- 결과를 경고하는 주석 (시간이 오래 걸리는 테스트 코드에 대한 경고)
- TODO 주석
- 특정 코드의 중요성을 강조하는 주석(75p)
- 공개 API에서 Javadocs
나쁜주석
- 이해가 안 되어 다른 모듈까지 뒤져야 하는 주석
- 코드의 내용을 그대로 단순 서술한 주석
- 정확하지 않은 정보가 있는 주석
- 의무적으로 다는 주석
- 변경 이력을 기록하는 주석
- 당연한 사실을 이야기하는 주석
- 함수나 변수로 표현할 수 있는 주석
- 배너와 같은 위치를 표시하는 주석
- 닫는 괄호에 어떤 괄호인지 표시하는 주석 (복잡하면 함수를 줄여라)
- 주석 처리된 코드 주석
- 전역 정보에 대한 주석
- TMI 주석
- 주석에서 지칭하는 코드가 모호한 주석 (89p)
- 함수 헤더
- 비공개 코드에서 Javadocs
inho ha / ian(swatchon) / iha(42seoul)