[클린 코드] 주석(2)

나쁜 주석

주석(1)에서 말한 케이스를 제외하고 나머지는 모두 나쁜 주석의 범주에 속한다.
일반적으로 대다수의 주석은 허술한 코드, 변명, 미숙한 결정을 합리화하는 독백이다.

- 주절거리는 주석
주석을 달기로 했다면 충분한 시간을 들여 최고의 주석을 달도록 노력하라.
특별한 이유 없이 의무가 또는 프로세스에서 하라고 하니까 주석을 단다면 시간낭비다.

다음 코드를 보자

public void loadProperties(){
    try{
        String propertiesPath = propertiesLocation + "/" + PROPERTIES_FILE;
        FileInputStream propertiesStream = new FileInputStream(propertiesPath);
        loadProperties.load(peropertiesStram);
    }catch(IOException e){
        //속성 파일이 없다면 기본값을 모두 메모리로 읽어 들임
    }
}

 

catch 블록에 있는 주석은 IOException이 발생하면 속성 파일이 없으므로 모든 기본값을 읽어 들인 상태인데
loadProperties.load를 호출하기 전에 읽어 들이는지,
loadProperties.load가 예외를 잡아 기본값을 읽어 들인 후 예외를 던지는지,
loadProperties.load가 파일을 읽어 들이기 전부터 모든 기본값부터 읽는지
catch에 대한 정확한 의도를 파악하기 어려워진다.

정확한 의도를 알기 위해서는 다른 코드들을 찾아봐야 하는데, 이해가 안 되어 다른 모듈까지 뒤져야 한다면
그 주석은 독자와 제대로 소통되지 않는 주석이다. 이러한 주석이 바이트 낭비되는 주석이다.

- 같은 이야기를 중복하는 주석
코드보다 더 적은 정보를 제공하는 주석은 코드보다 주석을 읽는 데에 시간을 더 오래 걸리게 한다.
아래 코드를 보자

//this.cloased가 true일 때 반환되는 유틸리티 메소드다.
//타임아웃에 도달하면 예외를 던진다.
public synchronized void waitForClose(final long timeoutMillis) throws Exception{
    if(!closed){
        wait(timeoutMillis);
        if(!closed)
            throw new Exception("MockResponseSender could not be closed);
    }
}

이 코드에 달린 주석은 코드를 정당화하는 주석도 아닌 것이 의도나 근거를 설명하는 주석도 아니다.
실제로 코드보다 부정확해 독자가 함수를 대충 이해하고 넘어가게 만든다.

- 오해할 여가 있는 주석
코드보다 읽기 어려운 주석에 담긴 살짝이라도 잘못된 정보는 프로그래머에게 오인하게끔 만들어 오용하도록 만들 수 있다.
프로그래머는 그 이유를 파악하는 데에 많은 시간과 노력을 들여 해결하는데 많은 시간을 쏟게 된다...

- 의무적으로 다는 주석
모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 하는 규칙은 절대 강제되지 않는다.
오히려 이런 주석은 코드를 복잡하게 만들고 혼란을 가져올 수 있다.
그러므로 꼭 필요한 경우이거나 상호 간 협의가 된 상태에서만 작성하도록 고려하자.
아래 코드는 주석의 무쓸모를 보여준다.

/**
 *
 * @param title CD 제목
 * @param author CD 저자
 * @param tracks CD 트랙 숫자
 * @param durationInMinutes CD 길이
 */
 public void addCD(String title, String author,
                     int tracks, int durationMinutes){

     CD cd = new CD();
     cd.title = title;
     cd.author = author;
     cd.tracks = tracks;
     cd.duration = durationMinutes;
     cdList.add(cd)
}

- 이력을 기록하는 주석
때때로 사람들은 모듈을 편집할 때마다 모듈 첫머리에 주석을 추가했는데, 이런 주석은 모듈에 가한 변경을 기록하는
일종의 로그가 되었다. 하지만 지금은 소스 코드 관리 시스템이 있으므로 쓸모없는 주석이다.

- 있으나 마나 한 주석
당연한 사실을 주석으로 제공하는 건 쓸모없다.
새로운 정보를 제공하는 주석이 되어야 한다.

//월 중 일자
private int dayOfMonth;

- 무서운 잡음
때로는 Javadocs도 잡음이다.
아래 Javadocs는 아무런 목적도 없이 작성되었다.

/** The name. */
private String name;

/** The version. */
private String version;

/** The licenceName. */
private String licenceName;

/** The version. */
private String info;

게다가 이 주석은 ctrl + C , ctrl + V까지 잘못했다.
여기서 이 주석을 읽는 독자는 아무런 정보도 도움도 받을 수 없다.

- 함수나 변수로 표현할 수 있다면 주석을 달지 마라
먼저 코드를 살펴보자

// 전역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
if (smodule.getDependSubsystems().contains(subSysMod.getSubsystem()){
    ...
}

이 코드에서 주석을 없애면 아래와 같다.

ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if(moduleDependees.contains(outSubSystem)){
    ...
}

위와 같이 주석을 생략하도록 코드를 개선할 수 있다.

- 위치를 표시하는 주석
간혹 가다 특정 위치를 표시하려고 아래와 같이 위치를 표시해놓는 주석이 있다.

/////////여기////////////////////////

일반적으로 이런 주석은 가독성을 낮추므로 제거하여야 하고, 특히 뒷부분에 작성한 슬래시로 이어지는 잡음은 제거해줘야 한다.

- 닫는 괄호에 다는 주석
때때로 닫는 괄호에 특수한 주석을 다는 사람들이 있다.
중첩이 심하고 긴 함수라면 의미가 있을지 모르지만, 작고 캡슐화된 함수에는 잡음일 뿐이다.
그러므로 닫는 괄호에 주석을 달아야 한다면 함수를 줄이도록 노력하자.

try{

    while(..){


    } //while

}//try

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

/* 내가 작성함 */

소스 코드 관리 시스템은 누가 언제 무엇을 추가하고 뺏는지 기록된다.
이런 쓸모없는 코드는 필요 없다.

- 주석으로 처리한 코드
협업하는 과정에서 주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다.
이유가 있어 남겨놓았다 혹은 중요하니까 지우면 안 된다고 생각한다.
본인이 직접 코드 정리를 하지 않으면 자리를 차지한다.
안 쓰면 지우자.

- HTML 주석
소스 코드에서 HTML 주석은 알맞지 않다.
소스 코드의 주석은 읽기 쉽고 편해야 한다. HTML 태그가 존재하는 주석은 아니다.

- 전역 정보
주석을 달 때 시스템의 전반적인 정보를 기술하지 말고, 근처에 있는 코드만 기술해라.
아래 코드를 보면 Javadocs 주석이 중복되었다는 사실 외에도 주석은 기본 포트 정보를 기술한다.
하지만 함수 자체는 포트 기본값을 전혀 통제하지 못한다.
즉 아래 주석은 바로 아래 함수가 아니라 시스템 어딘가에 존재하는 다른 함수를 설명하고 있다.

/**
 * 적합성 테스트가 동작하는 포트: 기본값은 <b>8082</b>.
 *
 * @param fitnessPort
 */
 public void setFitnessPort(int fitnessePort){
     this.fitnessePort = fitnessePort;
 }

- 너무 많은 정보
주석에 너무 많은 정보를 장황하게 설명하면 박찬호(TMI)와 다름없다.
필요한 정보만을 알려주고 몰라도 그만인 정보는 기술하지 말자.

- 모호한 관계
주석과 주석이 설명하는 코드는 둘 사이 관계가 명확해야 한다.

/*
 * 모든 픽셀을 담을 만큼 충분한 배열로 시작한다(여기에 필터 바이트를 더한다).
 * 그리고 헤더 정보를 위해 200바이트를 더한다.
 */
this.pngBytes = new byte[((this.width + 1) * this.height * 3) + 200];

여기서 필터 바이트는 무엇인지,
+1과 관련 있는지 *3과 관련 있는지 또는 둘 다 인지,
한 픽셀이 바이트인지,
200은 왜 더하는지 영문을 모른다.
주석을 다는 목적은 코드만으로 설명이 부족해서이다.

- 비공개 코드에서의 Javadocs
공개 API는 설명서 역할인 Javadocs가 필요하지만, 비공개라면 쓸모없다.
이는 유용하지 않을 뿐만 아니라 Javadocs 주석이 요구하는 형식으로 인해 코드만 보기 싫고 산만해진다.