[클린코드] 4장 주석

코드를 깔끔하게 정리해서 코드가 모든 것을 말해준다면 주석은 필요가 없다. 그리고 코드가 변화하고 합쳐지는 과정에서 주석도 그에 따라 유지 보수가 되어야하지만 사실상 쉽지가 않다(코드 유지보수도 힘들어 죽겠는데.. 주석까지..? 이런 느낌이 아닐까). 주석을 줄이고 되도록이면 코드로 의도를 표현하자.

 

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

주석을 쓰는 이유는 대개 코드의 품질이 나쁘기 때문이다. 코드가 어지럽고 복잡해서 주석을 쓰는거라면 차라리 그 시간에 코드를 더 깔끔히 만들어라.

 

코드로 의도를 표현하라

코드만으로 의도를 전달하기 힘든 경우가 있다. 그럴 때 주석이 필요하다고 말하지만, 주석 대신 함수로 설명해도 충분하다! 아래와 같이 주석 대신 함수명을 통해서 코드의 의도를 설명할 수도 있다.

// 학생이 장학금을 받을 자격이 있는지 검사한다.
if((student.gpa > 3.0) && (student.credits > 100))

if(student.isEligibleForScholarship())

좋은 주석

가장 베스트는 주석을 달지 않는 것이지만, 때로는 유익한 경우가 있다.

 

법적인 주석

예를 들어, 저작권 정보 혹은 소유권 정보를 주석으로 표기하는 경우다. 

 

정보를 제공하는 주석

해당 함수 혹은 변수의 기본적인 정보를 주석으로 제공하면 편리하긴 하지만 아까 말했듯이 제일 좋은건 주석 대신 좋은 명칭을 사용하는 것이다.

•  

// 현재 테스트 중인 A 인스턴스를 리턴한다
public abstract A respondInstance();

• 어떤 역할을 하는지
  • abstract 함수의 리턴 값이 어떻게 되는지

// kk:mm:ss
Pattern.compile("//d*://d*://d*);

• 단편화된 정보를 좀 더 깔끔하게 표현
  • 패턴 객체를 위한 형식 문자열을 정의할 때, 문자열들이 단편화 되어 가독성이 떨어질 경우 주석으로 깔끔하게 표현한다

의도를 설명하는 주석

이러한 로직을 왜 선택했는지 해당 결과는 어떤 의미를 가지고 있는지에 대한 내용을 주석으로 설명할 수도 있다.

return 0; // 우선 순위가 더 높다.

// 데드락을 상태를 만들기 위해 쓰레드를 대량으로 생성한다.
for(){
...
}

 

의미를 명료하게 밝히는 주석

인수나 반환값이 변경하지 못하는 코드라 명확한 의도를 코드로는 표현할 수 없다면, 의미를 명료하게 밝히기 위해 주석을 달아주는 것도 좋다. 그러나 실제 주석이 올바른지 검증하기 쉽지 않으므로 이 방식은 최대한 지양해야 한다.

assertTrue(aa.compareTo(ab) == -1); // aa < ab

 

결과를 경고하는 주석

다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용할 수도 있다. 예를 들어 특정 테스트 케이스는 특정한 상황에만 실행해야한 다면 주석을 달아주는 것이 좋다. (사실 @ignore로 대체 가능하다)

// 실행 시간이 길기 때문에 최종 테스트에서만 실행해주세요.

혹은 함수가 가져오는 위험 요인에 대해 언급을 해도 좋다.

// A는 쓰레드에 안전하지 않다
// 때문에 독립적으로 인스턴스를 생성 해주어야 한다.

그렇게 되면 위의 주석이 달린 함수를 사용해서 다른 작업을 하는 개발자가 주의해서 코드를 작성할 수 있다.

 

TODO 주석

앞으로 해야할 일을 주석으로 남겨두면 편하다. 요즘은 IDE로 TODO 주석이 있는 곳을 찾아 한 번에 보여주는 기능이 있어 프로그램을 완성한 이후 TODO 주석을 제거하기 수월해졌다(인텔리제이는 제공하더라 굳).

 

중요성을 강조하는 주석

쉽게 넘길 수 있지만 중요한 부분에 대해서는 주석으로 언급하는 것이 좋다.

// 반드시 1을 빼주어야 하는 이유가 모든 경우의 수가 0일 경우를 제외해주어야하기 때문이다.
return answer - 1;

 

공개 API에서 Javadocs

정확하고 풍부한 표현으로 작성된 Javadocs는 유용하다.

 

나쁜 주석

좋은 주석을 제외한 나머지 경우는 모두 나쁜 주석에 속한다. 

 

주절거리는 주석

이왕 주석을 달기로 했으면 제대로 달자. 어중간한 주석, 제대로 소통하지 못하는 주석은 오히려 혼란만 가중시킨다.

 

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

코드를 통해서 충분히 흐름을 파악할 수 있다면 굳이 주석을 달아주지 않아도 된다. 같은 이야기를 중복해서 말하는 것과 같다.

 

오해할 여지가 있는 주석

 

 

의무적으로 다는 주석

이력을 기록하는 주석

있으나 마나 한 주석

무서운 잡음

위치를 표시하는 주석

닫는 괄호에 다는 주석

공로를 돌리거나 저자를 표시하는 주석

주석으로 처리한 코드

HTML 주석

전역 정보

너무 많은 정보

모호한 관계

함수 헤더

비공개 코드에서 Javadocs

예제