책너두 5기 8일차
로버트 C. 마틴의 클린코드 p.67 ~ p.73
내용정리
4. 주석
나쁜 코드에 주석을 달지 마라. 새로 짜라.
브라이언 W. 커니핸, P. J. 플라우거
주석은 실패를 만회하기 위해 사용된다. 주석 없이는 자신을 표현할 방법을 찾지 못해 할 수 없이 사용하기 때문이다.
주석은 거짓말을 한다. 코드는 유지 보수 되지만 주석은 그렇지 않기 때문이다. 코드가 수정되고 변화하고 진화하지만 주석은 그대로면서 거짓이 되고 잘못된 정보를 퍼뜨린다.
엄격하게 관리된 주석이 필요할 수도 있지만, 결국 최선은 주석이 필요없는 코드이다.
주석은 나쁜 코드를 보완하지 못한다.
주석으로 중구난방인 코드를 설명할 시간에 코드를 보완 수정하라.
코드로 의도를 표현하라.
둘 중 어느 것이 더 나을까?
1
2
3
//직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) &&
(pmplyee.age > 65))
if (emplyee.isEligibleForFullBenefits())
명명으로 주석의 필요성을 해결할 수 있다.
좋은 주석
물론 안쓰는게 최선이지만 이런 주석들은 쓰는 것이 좋은 방법이 될 수도 있다.
법적인 주석
저작권 정보와 소유권 정보 등 회사에서 요구하는 주석
정보를 제공하는 주석
편리할지라도 가급적 이름에 담자.
의도를 설명하는 주석
의미를 명료하게 밝히는 주석
결과를 경고하는 주석
ex) //여유 시간이 충분하지 않다면 다음 테스트 케이스는 실행하지 마십시오
ex2) //이것은 스레드에 안전하지 못하니 각 인스턴스를 독립적으로 생성해야 한다.
TODO 주석
표시해놓고 주기적으로 검사하며 없애자.
중요성을 강조하는 주석
간과할만한 내용을 넣어두자.
공개 API에서 Javadocs
사용자에게 유용성을 주지만 잘못된 정보를 전달하지 않도록 유의해야한다.
읽고 나서
코드를 쓰면서 항상 주석을 통해 나의 생각과 코드의 진행방향을 꼼꼼하게 말하려고 노력했는데, 안쓰는게 최고라니 할말이 없다… 맞는말이긴 해서… 명명법에 더 신경써야겠다..
