[클린 코드] 주석 그리고 좋은 주석

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

주석은 오래될수록 코드에서 멀어진다.
오래될수록 완전히 그릇될 가능성도 커진다.
이유는 단순하다. 프로그래머들이 주석을 유지보수하기란 현실적으로 불가능하기 때문이다.

진실은 한곳에만 존재한다. 바로 코드다.
자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는 데 시간을 보내야한다.

⚙️ 코드로 의도를 표현하라

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

위의 코드는 아래와 같이 주석을 없애고 충분히 코드로 의도를 표현할 수 있다.

if(employee.isEligibleForFullBenefits()) {}

⚙️ 좋은 주석

어떤 주석은 필요하거나 유익하다.
하지만 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이다.

😀 법적인 주석

때로는 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣으라고 명시한다.
예를 들어 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보는 필요하고 타당하다.

😀 정보를 제공하는 주석

때때로 기본적인 정보를 주석으로 제공하면 편리하다.

// 테스트 중인 Responder 인스턴스를 반환한다. 
new Responder();

위와같은 주석은 유용할지라도, 가능하면 함수 이름에 정보를 담는 편이 더 좋다.

new ResponderBeingTested();

😀 의도를 표현하는 주석

때때로 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다.

😀 결과를 경고하는 주석

다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용할 수 있다.
예를 들면 다음같이 특정 테스트 케이스를 꺼야 하는 이유이다.

// 여유 시간이 충분하지 않다면 실행하지 마시오. 
const testWithReallyBigFile = () => {
  const bigFile = fetch('...');
  bigFile.map()...
}

😀 TODO 주석

앞으로 할일을 TODO 주석으로 남겨두면 편하다.
허나 TODO로 떡칠된 코드는 바람직하지 않다.
그러므로 주기적으로 TODO 주석을 점검해 없애도 괜찮은 주석은 없애야한다.

😀 중요성을 강조하는 주석

자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서도 주석을 사용할 수 있다.

const listITemContent = getListItem().trim();
// 여기서 trim은 정말 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다. 
// 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다. 
new ListItemWidget(listItemContent);