[Clean Code] 클린 코드(주석) - 9

주석

잘 달린 주석은 어떤 정보보다 유용하다. 하지만 경솔하고 근거없는 주석은 코드를 이해하기 어렵게 만든다
사실 주석이 필요한 코드는 실패다. 코드만으로 의도를 표현해야 한다. 이를 실패했기 때문에, 주석을 다는 것이다.

코드만이 정확한 정보를 제공하는 유일한 출처다

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

엉망인 코드에 주석을 다는 것보다 엉망인 코드를 손보는 것이 훨씬 좋다.

코드로 의도를 표현하라

코드만으로 의도를 설명하기 어려운 경우가 존재한다.

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

좋은 주석

어떤 주석은 필요하거나 유익하다.

법적인 주석

정보를 제공하는 주석

의도를 설명하는 주석

의미를 명료하게 밝히는 주석

a.compareTo(a) == 0; // a==a
a.compareTo(b) != 0; // a!=b

결과를 경고하는 주석

1. //여유 시간이 충분하지 않으면 실행하지 마십시오.
   최근에는 @Ignore("실행이 너무 오래걸린다.") 라는 Anotation을 이용해 테스트 케이스를 꺼버리지만, 이전에는 주석을 달았다.

2. //해당 객체는 스레드에 안전하지 못하다.
   // 따라서 각 인스턴스를 독립적으로 생성해야 한다.

TODO 주석

실제로 나도 자주 사용한다.
요즘 IDE는 TODO 주석을 찾아주는 기능을 제공해서 잊어버릴 염려는 없다. 그래도 너무 많은 TODO 주석은 좋지 않다.

중요성을 강조하는 주석

//여기서 a라는 객체는 정말 중요하다. a의 역할은 이며 ~으로 사용해야 한다.

나쁜 주석

위에서 언급되지 않은 주석들이 나쁜 주석이다.
좋지 않은 코드/실패한 코드를 커버하기 위한 주석 들이 대다수다.

주절거리는 주석

같은 이야기를 중복하는 주석

오해할 여지가 있는 주석

의무적으로 다는 주석

• 코드로도 충분히 이해할 수 있지만, 의무적으로 주석을 남겨 더 헷갈릴 여지를 주는 주석