[클린코드] 4장 주석

나쁜 코드에 주석을 달지마라. 새로 짜라.

• 브라이언 W. 커니핸, P.J. 플라우거

잘 달린 주석은 그 어떤 정보보다 유용하다. 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다. 오래되고 조합한 주석은 거짓말과 잘못된 정보를 퍼뜨려 해악을 미친다.

주석은 ‘순수하게 선하지’못하다. 사실상 주석은 기껏해야 필요악이다.
프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면, 주석은 거의 필요하지 않다.

우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다.
여기서 실패라는 단어를 썼다는 사실에 주목한다. 주석 없이는 표현할 방법을 찾지 못해 할 수 없이 주석을 사용했기 때문에 언제나 실패를 의미한다.
그러므로 주석은 반겨 맞을 손님이 아니다.

이 책에서 주석을 무시하는 이유가 무엇일까? 너무 자주 거짓말을 하니까. 주석은 오래될수록 코드에서 멀어진다.
이유는 단순하다. 프로그래머들이 주석을 유지보수 하기란 현실적으로 불가능하니까.
코드는 변화하고 진화한다. 불행하게도 주석이 언제나 코드를 따라가지 못한다. 코드에서 분리되어 점점 더 부정환한 고아로 변하는 사례가 너무난도 흔하다.

부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다. 부정확한 주석은 독자를 현혹하고 오도한다.
진실은 한곳에만 존재한다. 바로 코드다. 코드만이 정확한 정보를 제공하는 유일한 출처다. 그러므로 우리는 주석을 가능한 줄이도록 노력해야한다.

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

표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는 데 시간을 보내라!

코드로 의도를 표현하라!

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

// 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다. -> 선호하는 케이스
    if(employee.isEligibleForFullBenefits())

참조

• 클린코드