4장 주석

‘나쁜 코드에 주석을 달지 마라, 새로 짜라’

오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼트린다.

애초에 주석이 존재하는것 자체가 코드의 품질이 나쁘고 복잡하다.

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

이 코드보다,

if(employee.isEligibleForFullBenenfits()){
	//TODO
}

주석이 없는 두번째 코드가 더 의도를 파악하기 쉽다.

좋은주석 나쁜주석을 떠나 결국….

주석은 확실히 코드만으로 의도를 설명하기 어려운 경우 에만 사용하자.

좋은주석

• 법적인 주석
  • 저작권 정보와 소유권정보
• 정보를 제공하는 주석
  • 데이터 포맷 형식 시각과 날짜 등등…
• 의미를 명료하게 밝히는 주석
  • assertTrue(a.compareTo(a) == 0); // a == a
  • compareTo() 로 비교하는것을 주석으로 간단하게 설명
  • 물론 이또한 그릇되 의미의 주석을 달을 위험도가 높긴하다.
  좀 더 고민하고 주석을 달아보자.
• 결과를 경고하는 주석
  • 예를들어 실행 대기시간이 꽤 긴 테스트 케이스의 경우
  // 여유 시간이 충분하지 않다면 실행하지 마세요. 등으로 경고문을 작성할 수 있다.
• TODO 주석
  • //TODO
  • 현재 이 함수를 구현하지 않은 이유와 미래 모습을 TODO로 남기면 좋다.
  • 다만, 나쁜코드를 남겨놓는 핑계가 되어서는 안된다.
• 중요성을 강조하는 주석
• OpenAPI에서의 JavaDocs

나쁜주석

대다수의 주석이 나쁜 주석에 속한다.

• 주절거리는 주석
• 같은 이야기를 중복하는 주석
  • tomcat의 ContainerBase.java가 대표적인 예
  • 지저분하고 정신없게 만든다.
• 오해할 여지가 있는 주석
• 이력을 기록하는 주석과거에는 이력을 작성하는것이 바람직했다. (소스 코드 관리 시스템이 없었기 때문 )
• Git을 사용하는 지금 이력을 남기는 주석은 이제 혼란만 가중한다.
• /** *변경 이력 *2021년 10월 11일 : 클래스를 정리하고 패키지를 변경 *2021년 11월 5일 : 메서드를 추가했으며 클래스를 제거 ...... * 2022년 1월 2일 : 버그를 수정했다 **/
• 닫는 괄호에 다는 주석
• 주석으로 처리한 코드
  • 제일 꼴보기 싫으니 반드시 지우라고 로버트 마틴이 이야기한다.
  • 주석으로 처리된 코드는 다른 개발자가 지우기 주저함 (왠지 중요해보이기 때문에)
  • 이렇게 주석으로 처리된 코드가 하나둘씩 먼지 쌓이듯 쌓이게 된다.
• 너무 많은 정보가 적힌 주석

 

---

 

 

그래도 어느정도 주석을 적는편이 더 정보전달측에선 좋을거같다!