Ch4. 주석

4장은 주석에 대해서 다룬다.

잘 달린 주석은 그 어떤 정보보다 유용하다.
하지만 다른 의미로, 함수의 이름이나 변수의 이름만으로 의도를 정확하게 전달하지 못하고 주석으로 부가적인 설명이 필요하다는 말이 될 수도 있다.
이번 장에서는 좋은 주석과 나쁜 주석에 대해서 알아보자.

 

목차

목차

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

2. 코드로 의도를 표현하라

3. 좋은 주석

        (1) 법적인 주석

        (2) 정보를 제공하는 주석

        (3) 의도를 설명하는 주석

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

        (5) 결과를 경고하는 주석

        (6) TODO 주석

        (7) 중요성을 강조하는 주석

4. 나쁜 주석

        (1) 주절거리는 주석

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

        (3) 오해할 여지가 있는 주석

        (4) 의무적으로 다는 주석

        (5) 이력을 기록하는 주석

        (6) 있으나 마나 한 주석

        (7) 무서운 잡음

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

        (9) 위치를 표시하는 주석

        (10) 닫는 괄호에 다는 주석

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

        (12) 주석으로 처리한 코드

        (13) HTML주석

        (14) 전역 정보

        (15) 너무 많은 정보

        (16) 모호한 관계

        (17) 함수 헤더

        (18) 비공개 코드에서 Javadocs

---

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

코드가 복잡하고 엉망이어서 알아보기 힘들다고 주석을 달아야 할까요?

아닙니다.

주석을 다는게 아니라 코드를 고쳐야 합니다.

 

표현력이 풍부하고 깔끔한 주석 없는 코드가 복잡하고 어수선한 주석이 많이 달린 코드보다 훨씬 좋습니다.

주석은 단지 더러운 코드를 만회하려고 다는 변명과도 같습니다.

 

 

2. 코드로 의도를 표현하라

확실히 코드만으로 의도를 설명하기 어려운 상황이 존재합니다. 하지만 대다수의 경우, 조금만 더 생각하면 코드로 의도를 표현할 수 있습니다. 그러므로 최대한 주석 없이 코드만으로 의도를 표현하려고 노력해보세요.

 

---

좋은 주석

(1) 법적인 주석

때로는 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣으라고 명시합니다.

예를 들어, 각 소스 파일 첫 머리에 주석으로 들어가는 저작권 정보와 소유권 정보는 필요하고도 타당합니다.

 

(2) 정보를 제공하는 주석

때로는 기본적인 정보를 주석으로 제공하면 편리합니다.

예를 들어, 다음 주석은 추상 메서드가 반환할 값을 설명합니다.

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

위와 같이 정보를 제공하는 주석이 유용하다고 하더라도, 아래 예시처럼 되도록이면 주석이 필요 없을 정도로 함수 이름에 정보를 담는 편이 좋습니다.

protected abstract Responder responderBeingTested();

 

(3) 의도를 설명하는 주석

주석으로 구현을 이해하게 도와주는 것 뿐만 아니라, 결정에 깔린 의도까지 설명하는 경우도 있습니다.

이 경우, 내가 이러이러한 이유로 이렇게 코드를 짰는데 소스코드를 읽는 사람이 이 코드를 짠 사람의 문제 해결 방식에 동의하지 않을지라도 ' 왜 ' 이렇게 코드를 작성했는지 주석을 통해 이해할 수 있습니다.

 

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

대체로 인수나 반환값을 의미를 읽기 좋게 표현하면 이해하기 쉬워집니다. 하지만 반환값이 표준 라이브러리 같이 변환하지 못하는 코드에 속한다면, 의미를 명료하게 밝히는 주석이 유용합니다.

 

(5) 결과를 경고하는 주석

때때로 다른 프로그래머에게 결과를 경고하려는 목적으로 주석을 씁니다.

아래 예시처럼 말입니다.

public static SimpleDateFormat makeStandardHttpDateFormat() {

    // SimpleDateFormat은 thread에 안전하지 못하다
    // 따라서 각 인스턴스를 독립적으로 생성해야 한다
    SimpleDateFormat sdf = new SimpleDateFormat("EEE, dd MMM   yyyy HH:mm:ss z");
    sdf.setTimeZone(TimeZone.getTimeZone("GMT"));
    return sdf;
    
}

 

(6) TODO 주석

때로는 앞으로 할 일을 // TODO 주석으로 남겨두면 편합니다.

다음은 함수를 구현하지 않은 이유와 미래 모습을 // TODO 주석으로 설명한 예제입니다.

// TODO-MdM 현재 필요하지 않다
// 체크아웃 모델을 도입하면 함수가 필요 없다
protected VersionInfo makeVersion() throws Exception {
    return null;
}

TODO 주석은 프로그래머가 필요하다고 여기지만 당장 구현하기 어려운 업무를 기술합니다.

또한, 더 이상 필요 없는 기능을 삭제하라는 알림, 누군가에게 문제를 봐달라고 하는 요청, 더 좋은 이름을 떠올려달라는 부탁, 앞으로 발생한 이벤트에 맞춰 코드를 고치라는 주의 등에 유용합니다.

하지만 어떤 용도로 사용하든 시스템에 나쁜 코드를 남겨 놓는 핑계가 되어서는 안됩니다.

그러므로 주기적으로 TODO 주석을 점검하여 없애도 괜찮은 주석은 없애는 게 좋습니다.

 

(7) 중요성을 강조하는 주석

자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서도 주석을 사용합니다.

/* 예시 */

String listItemContent = match.group(3).trim();
// 여기서 trim은 정말 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다.
// 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다.

new listItemWidget(this, listItemContent, this.level + 1);
return buildList(text.substring(match.end()));

 

---

나쁜 주석

(1) 주절거리는 주석

실제로 나는 주석으로 주절거린 적이 많았다. 반성한다..

읽어서 이해할 수 없는 주석은 다른 모듈까지 뒤져야 하는 사태를 발생시킨다. 코드를 작성한 본인만 아는 주석, 즉 주절거리는 주석은 독자와 제대로 소통하지 못하는 주석이다.  

 

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

코드 내용을 그대로 중복한 주석은 코드보다 더 많은 정보를 제공하지도 못하고, 의도나 근거를 설명하는 주석도 될 수 없다. 이러한 주석은 코드만 지저분하고 정신 없게 만든다.

예를 들면, 아래와 같은 주석을 중복하는 주석이라고 할 수 있다.

/**
* 이 컴포넌트를 지원하기 위한 생명주기 이벤트
*/
protected LifecycleSupport lifecycle = new LifecycleSupport(this);

/**
* 컨테이너와 관련된 Loader 구현
*/
protected Loader loader = null;

나는 위와 같이 한글 주석으로 코드 내용을 써놓으면 이해하기 쉬울 것이라고 생각했다. 그래서 나도 종종 코드를 작성할 때 중복하는 주석을 많이 썼다. 그런데 지금 보니 코드 길이만 길어질 뿐, 주석만 없었다면 두 줄로 끝날 코드였다....

 

(3) 오해할 여지가 있는 주석

제대로 달지 않은 주석에 담긴, '살짝 잘못된 정보'로 인해 오해의 여지가 생긴다면, 언젠가 잘못된 이해로 그 함수를 호출했을 때 생긴 잘못된 결과에 대해 오류를 찾기 힘들어 질 수도 있다.

 

(4) 의무적으로 다는 주석

모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 코드를 복잡하게 만드며, 혼동과 무질서를 초래한다. 역시나 코드만 길어질 뿐, 아무 의미 없는 주석이 되어버린다.

예시 :
/**
*
* @param title CD 제목
* @param author CD 저자
* @param tracks CD 트랙 숫자
*/
public void addCD(String title, String author, int tracks) {
    CD cd = new CD();
    cd.title() = title;
    cd.author = author;
    cd.tracks = tracks;
    cdList.add(cd);
}

 

(5) 이력을 기록하는 주석

작성중

 

(6) 있으나 마나 한 주석

작성중

 

(7) 무서운 잡음

작성중

 

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

작성중

 

(9) 위치를 표시하는 주석

작성중

 

(10) 닫는 괄호에 다는 주석

작성중

 

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

작성중

 

(12) 주석으로 처리한 코드

작성중

 

(13) HTML 주석

작성중

 

(14) 전역 정보

작성중

 

(15) 너무 많은 정보

작성중

 

(16) 모호한 관계

작성중

 

(17) 함수 헤더

작성중

 

(18) 비공개 코드에서 Javadocs

작성중

 

 

 

 

4장을 마치며

주석을 남긴다는 것은 대체로 내 코드가 의도를 제대로 나타내지 못하는 명료하지 못한 코드임을 증명하는 것과 같다.
최대한 주석을 남기지 않고 코드와 이름에 의도와 개념을 부여하고, 정말 코드로 표현하지 못하는 것이나 필요한 정보만을 주석으로 남겨야 한다.

나는 지금까지 코드를 짜면서 주석으로 주절거린 적이 많았고, 코드에 충분히 의도가 담겼지만 중복된 내용을 주석으로 또다시 남길 때도 많았다. 앞으로는 최대한 주석을 없애고 명료하고 깨끗한 코드를 만들도록 노력해야겠다.