Clean Code (클린코드) | 4. 주석 074-083

요약

좋은 주석과 그렇지 못한 주석에 대한 예제 코드와 함께 설명한다.

 

좋은 주석

TODO 주석: 앞으로 할일을 작성하는 주석으로 주기적으로 확인하여 지워도 되는 주석은 삭제하는 것이 좋다.

중요성을 강조하는 주석: 자칫 놓칠 수 있는 중요성에 대해 작성한다.

공개 API에서 Docs: 공개 API를 구현할 떄는 표준 라이브러리에서 사용한 Official Docs를 사용한다. (JS 에서는 JSDocs가 있음)

 

나쁜 주석

이유없이 주절거리는 주석: 소통이 안 되고 무의미한 주석

같은 이야기를 중복하는 주석: 같은 코드 내용을 그대로 설명한 주석

오해할 여지가 있는 주석: 코드와 딱 맞아 떨어지지 않아 프로그래머가 잘못 해석할 수 있는 주석

의무적으로 다는 주석: 모든 함수나 변수에 주석을 달아야 한다는 규칙은 불필요하다.

이력을 기록하는 주석: 예전엔 소스 코드 관리 시스템이 없어서 모듈 첫 머리에 변경 이력을 관리하곤 했지만, 지금은 필요 없다.

있으나 마나한 주석: 너무 당연한 사실을 언급하고 새로운 정보를 제공하지 못하는 주석

 

 

발췌

주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다.

주석을 적게 쓰는 것이 좋지만, 써야 하는 상황에서는 그 효과를 발휘할 수 있도록 시간을 투자해 “잘” 작성해야 한다.

 

메모

전반적으로 주석의 좋은 예, 나쁜 예를 나열하고 있는데 지금까지 읽은 내용을 토대로 하면

“주석은 코드 이외의 새로운 유의미한 정보를 제공하는 경우에 한해 작성하라”가 되는 듯하다.