📚 4장 주석

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

모듈을 짜고 보니 짜임새가 엉망이고 알아먹기 어렵다. 지저분한 모듈이라는 사실을 자각한다. 그래서 자신에게 이렇게 말한다. “이런!주석을 달아야겠다!” 아니다! 코드를 정리해야 한다.

코드로 의도를 표현하라!

다음 코드 예제 두 개를 살펴보자.

// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))

다음 코드는 어떤가?

if (employee.isEligibleForFullBenefits())

코드로도 대다수의 의도를 표현할 수 있다.

좋은 주석

• 법적인 주석
• 정보를 제공하는 주석
• 의도를 설명하는 주석
• 의미를 명료하게 밝히는 주석
• 결과를 경고하는 주석
• TODO 주석
• 중요성을 강조하는 주석
• 공개 API에서 Javadocs

좋은 주석의 예가 있더라도, 주석은 작성하다가도 틀린 정보를 제공할 위험이 있기 때문에 가능한 주석은 사용하지 않는 것이 좋다.

나쁜 주석

• 주절거리는 주석
• 같은 이야기를 중복하는 주석
• 오해할 여지가 있는 주석
• 의무적으로 다는 주석
• 이력을 기록하는 주석
• 있으나 마나 한 주석
• 위치를 표시하는 주석
• 닫는 괄호에 다는 주석 → 대신 함수를 줄이자
• 공로를 돌리거나 저자를 표시하는 주석
• 주석으로 처리한 코드 → 소스 코드 관리 시스템에 기록이 남음
• HTML 주석 → 읽기가 어렵다. IDE에서조차 읽기 어렵다.
• 전역 정보 → 코드 일부에 주석을 달면서 시스템 전반적인 정보 기술x
• 너무 많은 정보
• 모호한 관계
• 함수 헤더
• 비공개 코드에서 Javadocs