[클린코드] 4장 주석

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

 

주석이 안 좋은 이유

• 주석은 오래될수록 코드에서 멀어진다.
• 주석을 유지하고 보수하기란 현실적으로 불가능하다.
• 처음부터 주석이 없는 방향으로 코드를 구현하는 것이 좋다.
• 부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다.

그러므로 우리는 주석을 가능한 줄이도록 노력해야 한다.

 

 

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

• 코드에 주석을 추가하는 이유는 코드의 품질이 나쁘기 때문이다.
• 난장판으로 어질러 놓은 코드를 주석으로 설명할 시간에 난장판을 깨끗이 치우자

 

코드로 의도를 표현하자

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

if (employee.isEligibleForFullBenefits())

두 개의 코드 중 어떤 것이 의도를 알 수 있는 코드일까?

주석으로 달려는 설명은 함수 이름으로 표현해도 충분하다.

 

좋은 주석

• 법적인 주석 : 저작원 정보 및 소유권 정보
• 정보를 제공하는 주석 : 추상메서드 반환 값 및 정규표현식 예시
• 의미를 명료하게 밝히는 주석 : 변경하지 못하는 모호한 인수나 표준 라이브러리 반환값
• TODO 주석 : 앞으로 할 일
• 중요성을 강조하는 주석 : 대수롭지 않다고 여겨질 뭔가의 중요성을 강조
• 공개 API에서의 javadocs

 

나쁜 주석

• 주절거리는 주석 : 의미가 확실하지 않으면 독자와 소통하지 못하는 주석이 됨
• 같은 이야기를 중복하는 주석 : 코드 내용이 중복되는 주석
• 오해할 여지가 있는 주석 : '살짝 잘못된 정보'만으로 다른 프로그래머가 고생함
• 있으나 마나 한 주석 : ex) 기본 생성자 위에 기본 생성자라고 작성 → 이미 모두가 알고 있는 사실
• 저자를 표시하는 주석 : 소스 코드 관리 시스템은 누가 코드를 작성했는지 이미 알고 있음
• 주석으로 처리한 코드 : 다른 사람들이 지우기를 주저함. 의미가 있어서 남겨두었다고 생각하기 때문