나쁜 코드에 주석을 달지 말라. 새로 짜라. - 브라이언 W. 커니핸, P.J. 플라우거
- 잘 달린 주석은 그 어떤 정보보다 유용하다.
- 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다.
- 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨린다.
- 사실 주석은 필요악 이다. 프로그래밍 언어의 표현력을 높힌다면 주석은 필요없다.
- 우리는 의도를 표현하지 못한, 실패를 만회하기 위해 주석을 작성한다.
- 주석은 언제나 실패를 의미한다.
- 코드로 의도를 표현 할때 마다 스스로를 칭찬해준다.
주석을 달때마다 표현력이 없다는 것을 푸념해라.
- 애초에 주석이 필요없는 방향으로 코드를 작성해라.
- 진실은 언제나 코드에만 존재한다.
주석은 나쁜 코드를 보완하지 못한다.
주석을 추가하는 일반적인 이유는, 코드의 품질이 나쁘기 때문이다.
주석을 정리한다? (X) → 코드를 정리한다! (O)
코드로 의도를 표현하라!
// ASIS
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))
// TOBE
if (employee.isEligibleForFullBenefit())좋은주석
안쓰는게 최선이나 유익한 주석이 있다.
‣ 법적인 주석
- 소스파일 첫머리의 저작권/ 소유권 과 같은 계약조건 법적인 정보. (IDE에서 주석 헤더를 자동으로 축소해줌)
‣ 정보를 제공하는 주석
// 테스트 중인 Responder 인스턴스를 반환한다.
protected abstract Responder responderInstance();- 반환값을 명시 ⇒ 함수명으로 표현하는것 추천 ex. responderBeingTested
// kk:mm:ss EEE, MMM dd, yyyy 형식이다.
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");- 정규표현식에 대한 설명 ⇒ 시각과 날짜를 변환하는 클래스로 추출하는 것 추천.
‣ 의도를 설명하는 주석
‣ 의미를 명료하게 밝히는 주석
‣ 결과를 경고하는 주석
‣ TODO 주석
‣ 중요성을 강조하는 주석
‣ 공개 API에서 Javadocs
나쁜 주석
‣ 주절거리는 주석
‣ 같은 이야기를 중복하는 주석
‣ 오해할 여지가 있는 주석
‣ 의무적으로 다는 주석
‣ 이력을 기록하는 주석
‣ 있으나 마나 한 주석
‣ 무서운 잡음
‣ 함수나 변수로 표현할 수 있다면 주석을 달지 마라
‣ 닫는 괄호에 다는 주석
‣ 공로를 돌리거나 저자를 표시하는 주석
‣ 주석으로 처리한 코드
‣ HTML 주석
‣ 전역정보
‣ 너무 많은 정보
‣ 모호한 관계
‣ 함수 헤더
‣ 비공개 코드에서 Javadocs
‣ 예제
Later never comes 👩🏻💻