[CleanCode] 4장. 주석

목차

1. 주석은 나쁜 코드를 보완하지 못한다
2. 코드로 의도를 표현하라
3. 좋은 주석
4. 나쁜 주석

---

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

모듈이 지저분하다면 주석을 다는것이 아니라 코드를 정리해야 한다.

 

코드로 의도를 표현하라

Bad :

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

Good :

if (employee.isEligibleForFullBenefits())

 

좋은 주석

• 법적인 주석
• 정보를 제공하는 주석
  코드를 개선하면 없앨 수 있는 주석이다.
• 의도를 설명하는 주석
  소스 코드의 알고리즘을 결정하게 된 의도를 설명하는 주석
• 의미를 명료하게 밝히는 주석
  인수나 반환값이 변경하지 못하는 코드일 경우 의미를 명료하게 밝히는 주석 (이 또한 오류가 존재하더라도 확인이 어려워지니 고민하고 정확히 달도록 해야 한다.)
• 결과를 경고하는 주석
• TODO 주석
• 중요성을 강조하는 주석
• 공개 API에서 Javadocs

 

나쁜 주석

• 주절거리는 주석
• 같은 이야기를 중복하는 주석
• 오해할 여지가 있는 주석
• 의무적으로 다는 주석
• 이력을 기록하는 주석
• 있으나 마나 한 주석
• 무서운 잡음
• 함수나 변수로 표현할 수 있다면 주석을 달지 마라
• 위치를 표시하는 주석
• 닫는 괄호에 다는 주석
• 공로를 돌리거나 저자를 표시하는 주석
• 주석으로 처리한 코드
• HTML 주석
• 전역정보
• 너무 많은 정보
• 모호한 관계
  주석이 코드의 부족한 설명 외에 도메인 지식이 있어 추가적인 설명이 필요한 경우는 최악
• 함수 헤더
• 비공개 코드에서 Javadocs