4장. 주석(clean code)

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

• 주석은 가능한 줄이자.

코드로 의도를 표현하라!

if((employee.flags & HOURLY_FLAG) && (employee.age > 65))

if(employee.isEligibleForFullBenefits())

• 전자보다는 후자가 낫다

 

좋은 주석

• 법적인 주석
• 정보를 제공하는 주석 ex) 추상 메서드가 반환할 값 설명
• 의도를 설명하는 주석
• 의미를 명료하게 밝히는 주석
  • ex) assertTrue(a.compareTo(a) == 0);  // a == a
• 결과를 경고하는 주석
  • 다른 프로그래머에게 결과를 경고할 목적 ex) // 여유 시간이 충분하지 않다면 실행하지 마십시오.
• TODO 주석
  • 앞으로 할 일 ex) 더 이상 필요 없는 기능을 삭제하라는 알림, 누군가에게 문제를 봐달라는 요청 등
• 중요성을 강조하는 주석
  • 중요성을 강조하기 위해 사용

나쁜 주석

• 주절거리는 주석
• 같은 이야기를 중복하는 주석 - 코드 내용을 중복할 경우
• 오해할 여지가 있는 주석
  • 살짝 잘못된 정보가 있는 경우
• 의무적으로 다는 주석
• 이력을 기록하는 주석
• 있으나 마나 한 주석
  • 당연한 사실을 언급
• 주석으로 처리한 코드

 

review

나는 주석을 잘 쓰지않는 편이다. 코드로 의도를 표현하기에 충분하다고 생각해 주석은 잘 쓰지 않는데, 좋은 주석을 쓰니 의미가 더 명확해 지는 이점도 있으니 활용해야겠다. 🏃

 

출처) clean code / 인사이트