잊을 때쯤 한번 다시 읽어봐야할 Clean code에 관하여 (주석)

3. 주석 

- 저자는 주석에 대해 Clean Code를 코드로만 달성하는 것이 실패해서 넣는 것을 주석이라고 말한다.

- 특히 그는 주석은 오래될 수록 실제 돌아가는 코드와 멀어지게 되며 프로그래머들이 주석까지 다 유지보수를 하기엔 쉽지 않다고 말하고 있다.

• 주석은 애시당초 처음부터 나쁜 코드는 보완하지 못 한다.
  • 코드로 의도를 표현해야 한다. 

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

if (employee.isEligibleForFullBenefits()) {
	...
}

처음부터 주석으로 설명해야만 하는 코드가 아닌 후자처럼 주석이 필요없는 코드가 이상적이다.

 

• 그나마 좋은 주석의 조건은 아래라고 필자는 말한다. (동시에 그래도 없는게 제일 낫다고 함)
  • 정보를 제공하는 주석 
    • 예를 들면 추상 메서드가 반환할 값을 설명한다든가, 정규 표현식에 대한 설명을 한번에 볼 수 있게 써 놓는 것이 있다.
  • 의도를 설명하는 주석 
    • 왜 이렇게 개발을 했었는지에 대한 결정에 깔린 의도까지 설명하는 주석은 가치가 있다. 
  • 결과를 경고하는 주석
    • 다른 개발자에게 결과를 경고할 목적으로 주석을 사용할 수 있다.
    • 예를 들면 특정 테스트 코드에 대해서는 소요시간이 오래 걸리니 실행할 때 조심해라는 주석을 달 수 있다. 
  • TODO 주석 
• 아래의 주석들은 오히려 달지 않는 것이 좋은 주석이다. 
  • 의무적으로 다는 주석
    • 전회사에서도 했던 건데 @param title ~~ @param 이런 식으로 하는 것 
    • 이건 변수명만 봐도 알 수 있게 코드를 작성했어햐 했다. 
  • 이력을 다는 주석 
  • //기본 생성자 // 월 중 일자를 반환한다. 와 같은 안 봐도 알 수 있는 함수의 주석 
  • 닫는 괄호에 다는 주석
    • 이는 함수가 복잡할 때 보통 다는데 '여기 닫는 괄호는 while의 괄호고 여기 닫는 괄호는 if의 괄호이다' 이런식으로 이거 자체가 clean code에서 멀어져있으니 추상화를 낮춰 쪼갠다. 
  • 누가 개발했는지 쓰지 마라 
  • 코드를 주석처리 해놓지 마라 
    • 이건 후에 제3자가 보면 지우기 주저하게 만든다. 
  • 전역 정보에 대한 주석