클린코드 4장 주석

나쁜 코드에 주석을 달지마라. 새로 짜라. - 브라이언 w커니핸 플라우거

잘 달린 주석은 유용하지만, 경솔하고 근거없는 주석은 코드를 이해하고 어렵게 만든다. 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨린다.

주석은 쉰들러리스트가 아니다. 순수하게 선하지 못하다. 코드 자체가 표현력이 풍부하다면, 주석은 필요하지 않다. 우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다. 주석은 언제나 실패를 의미한다.

주석은 오래될수록 코드에서 멀어진다. 오래될수록 완전히 그릇될 가능성도 있다. 프로그래머들이 주석을 유지보수하긴 현실적으로 불가능하다. 주석이 언제나 코드를 따라가진 않는다.

주석을 엄격하게 관리하느니, 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로 에너지를 쏟아라. 부정확한 주석은 아예 없는 것 보다 나쁘다.

진실은 한 곳에 존재한다. 바로 코드다. 코드만이 자기가 하는 일을 진실되게 말한다.

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

• 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하며 어수선하고 주석이 많이 달린 코드보다 훨씬 좋다.

코드로 의도를 표현하라. #

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

• 위 코드보다 아래 코드가 훨씬 낫다.
• 주석이 없어도 코드로 의도를 표현할 수 있다.

좋은 주석 #

• 법적 정보
• 정보 제공

  // kk:mm:ss EEE, MMM, dd, yyyy 형식이다.
  Pattern timeMatcher = Pattern.compile( ... )
  

  • 위 코드는 정규표현식이 시각과 날짜를 뜻한다고 설명한다.
  • 이왕이면 시각과 날짜를 변환하는 클래스를 만들어 코드를 옮겨주면 더 좋고 깔끔하겠다.
• 의도를 설명하는 주석
• 의미를 명료하게 밝히는 주석
• TODO 주석
• 중요성을 강조하는 주석

위 주석들 중 내 생각에 꼭 필요한건 법적정보와 TODO 뿐인 것 같다. 나머지는 없앨 수 있다면 없애는게 더 낫다.

나쁜 주석 #

• 주절거리는 주석
  • 특별한 이유 없이 의무감으로 혹은 프로세스에서 하라고 하니까 마지못해 주석을 단다면 시간낭비다.
• 같은 이야기를 중복하는 주석
  • 코드 내용을 그대로 중복설명
• 오해할 여지가 있는 주석
• 의무적으로 다는 주석
  • javadocs
• 이력을 기록하는 주석
  • git 쓰니까 필요없음
• 함수나 변수로 표현할 수 있다면 주석을 달지 마라
• 생략

대다수의 주석은 나쁘다. 코드로 의도를 표현하자.