Clean Code: 주석

로버트 C. 마틴의 클린 코드를 읽고 있는데, 좋은 내용들이 많아 기억하고자 포스팅 한다.
그 첫번째 항목은 주석.

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

주석은 코드로 의도를 표현하지 못해, 실패를 만회하기 위해 사용하는 것.
주석이 필요한 상황에 다시금 코드로 의도를 표현하기 위해 고민하라.

왜냐하면 개발자가 코드를 유지,보수하는 것 만큼이나 주석을 유지, 보수하기 어렵기 때문.
그렇게 되면 오래되고 잘못된 주석이 남기 쉬운데, 이는 없느니만 못하다.

하지만 어떤 주석은 필요하거나 유익하다.

좋은 주석이란?

• 법적인 주석
  : 저작권, 소유권, 계약 조건, 법적인 정보, 표준 라이선스 등을 담고 있는 주석

• 정보를 제공하는 주석
  : 때로는 기본적인 정보를 주석으로 제공한다.
  하지만 가능한한 함수 이름에 정보를 담는 편이 더 좋다.

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

• 의미를 명료하게 밝히는 주석
  : 때때로 모호한 인수나 반환값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워진다.

• 결과를 경고하는 주석
  : 때로 다른 프로그래머에게 결과를 경고 할 목적으로 주석을 사용한다.

• TODO 주석
  : '앞으로 할 일'을 //TODO 주석으로 남겨두면 편하다. 프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무를 기술한다. 더 이상 필요없는 기능을 삭제하라는 알림, 누군가에게 문제를 봐달라는 요청, 더 좋은 이름을 떠올려달라는 부탁, 앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의 등에 유용하다.

• 중요성을 강조하는 주석

그렇다면 반대로 나쁜 주석에는 어떤 것들이 있을까?

• 주절거리는 주석
  : 읽는 사람이 이해가 안되어 다른 모듈까지 뒤져야 하는 주석은 바이트만 낭비할 뿐이다.

• 같은 이야기를 중복하는 주석

• 오해 할 여지가 있는 주석

• 있으나 마나 한 주석

//기본 생성자
protected AnnualDateRul(){
}

• 위치를 표시하는 주석

//action //////////////////

• 닫는 괄호에 다는 주석
  : 중첩이 심하고 장황한 함수라면 의미가 있을지 모르나, 작고 캡슐화된 함수에서는 잡음일 뿐이다. 닫는 괄호에 주석을 다는 대신 함수를 줄이려 시도하는 것이 좋다.
• 공로를 돌리거나 저자를 표시하는 주석, 이력을 기록하는 주석, 주석으로 처리한 코드
  : 소스 코드 관리 시스템에 저장 할 수 있기에 달지 않는 편이 좋다.
• 전역 정보
• 너무 많은 정보
• 예제

.
.
.

주석을 깔끔하게 쓰거나 아예 쓰지 않길 원한다면 그만큼 코드로 명확한 의도를 밝힐 수 있어야겠다.