[Clean Code] 좋은 주석 vs 나쁜 주석

클린코드의 저자는 주석이 사실상 필요악이라고 말한다. 

주석을 사용하는 것은 거의 대부분 실패한 경우이기 때문에, 가능한 안쓰는게 좋다고 말이다.

특시 주석은 코드를 수정할 때 자동으로 수정되지 않는 부분이기 때문에, 유지보수가 어렵다는 큰 단점이 있다.

 

애초에 주석이 없는 게 좋지만..

만약 꼭 써야만 한다면, 어떤 것이 좋고 나쁜 주석일까?

 

좋은 주석

• 법적인 이유로 주석을 넣어야 하는 경우
• 기본적인 정보를 제공하는 경우
• 결정에 대한 이유를 설명하는 주석
• 모호한 인수나 반환값의 의미를 밝히는 주석
• 다른 개발자에게 결과를 경고하는 내용
• 앞으로 할 일 (//TODO)
• 쉽게 넘어갈 수 있는 부분의 중요성을 강조할 때
• 공개 API를 구현할 경우 Javadocs 작성

 

나쁜 주석

• 이유 없이 의무감으로 작성한 주석
• 관련 없는 정보를 장황하게 작성한 내용
• 같은 코드의 내용을 그대로 반복한 주석
• (의도와 달리) 오해의 여지가 있는 내용
• 모든 함수에 Javadocs를 달거나, 모든 변수에 주석을 달 필요는 없다!
• 너무 당연한 내용은 주석에 작성하지 않도록 하자
• 함수나 변수로 표현할 수 있다면 주석을 달지 말자
• 소스 파일에서 특정 위치를 표시하는 주석 (ex. ////// Actions /////// )
  → 배너를 남용하면 독자가 쓸데없는 내용으로 여기고 무시하기 쉽다
• 닫는 괄호에 다는 주석
  → 주석 대신 함수를 줄이도록 노력해보자
• 저자를 표시하는 주석은 필요 없다
• 코드를 주석으로 처리하지 말자
• HTML 주석은 혐오 그 자체! 
• 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 말자 
  → 주석을 단다면 근처에 있는 코드만 기술하자
• 주석과 코드 간의 관계는 명확해야 한다
• 짧은 함수는 주석으로 헤더를 추가할 필요가 없다
• 비공개 코드에서 Javadocs는 쓸모없다