Clean Code - 주석

코드는 항상 변화하고 진화한다. 불행하게도 주석은 언제나 따라 가지는 않는다. 주석은 필요악이다.

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

자신이 저지른 난장판을 주석으로 설명하려 하는 대신에 그 난장판을 깨끗이 치워라.

코드로 의도를 표현하라.

코드를 주석으로 설명하지 말고, 더 명확하게 클래스나 함수로 표현해라.

좋은 주석

라이선스에 관한 주석을 붙이는 것은 타당하다. 의도를 설명하는 주석은 옳을 수 있다. 

앞으로 할 일을 TODO 주석으로 남겨두면 편하다. 공개 API를 구현했다면 Javadocs를 남겨야 한다.

나쁜 주석

주절거리는 주석.

코드의 내용을 그대로 설명하는 주석은 필요가 없다.

자바docs를 만들기 위한 의무적인 주석도 좋지 않다.

/**

*

* @param title CD 제목

*/

이력을 기록하는 주석은 이제 필요가 없다. 소스코드 관리시스템을 사용하면 된다.

있으나 마나한 주석은 달지 말자.

/**

* 기본 생성자

*/

무서운 잡음. 주석은 모두 달기 위해 카피 앤 붙이기를 하다가 다른 정보를 주석으로 달았다면 끔찍한 일이다.

함수나 변수로 표현할 수 있다면 주석을 달지 마라.

위치를 표시하는 주석. 이것도 정말 나쁜 습관이다.

닫는 괄호에 주석을 표시했다면 블록을 더욱 단순하게 만들어라.

공로를 돌리거나 저자를 표시하는 주석은 달지마라. 소스관리시스템이 있다.

/** 닉이 추가한 기능 */

주석으로 처리한 코드. 이 경우도 소스관리시스템이 있다. 오히려 주석처리를 하면 쉽게 지우지 못한다.

HTML 주석. 자바doc을 위해 HTML 주석을 다는 경우 있다. 프리젠테이션은 툴이 해야할 일이지 개발자가 해야할 일은 아니다.

너무 많은 정보를 주석으로 달지 마라. 간단 명료하지 않으면 주석을 읽기 싫어질 것이다.

비공개 코드라면 자바doc을 달지 마라.