11. 주석 작성 방법

주석은 코드를 더 쉽게 이해하는 데 도움이 되기 위해 작성하지만, 오히려 읽는 사람을 혼란스럽게 만들 수도 있다. 읽는 사람에게 도움을 주어 유지 보수와 변경의 정확성을 높이는 주석 작성 방법에 대해 알아보자.

1. 내용이 낡은 주석

서비스의 사양은 계속해서 변화한다. 하지만, 업무가 바쁘고 충분히 주의하지 않으면 코드가 변경되면서 주석은 변경되지 않는 경우가 생긴다. 이처럼, 정보가 오래되어 구현 상태를 제대로 설명하지 못하는 주석은 내용이 낡은 주석이므로 주의해야 한다. 가짜 정보를 담고 있는 주석은 읽는 사람에게 혼란을 주고, 이로 인해 버그를 발생시킬 가능성이 있다. 주석이 낡아 버리지 않게, 구현을 변경할 때 주석도 함게 변경하는 것이 좋다. 이 때, 주의해야 할 점은 아래와 같다.

1. 주석은 실제 코드가 아님을 이해하기
   • 실제 코드가 아닌 말 또는 주석은 실제 코드가 아니므로 실제 내용을 100% 설명할 수는 없다.
2. 로직의 동작을 설명하는 주석은 낡기 쉽다.
   • 코드의 동작을 그대로 설명하는 주석은 코드를 변경할 때마다 주석도 변경해야 한다. 이는 시간이 지나면서 실수로 변경이 누락될 수 있고, 실제 내용과 다르게 바뀔 가능성도 있다.
   • 또한, 주석을 달았기 때문에 안심하여 클래스와 메서드의 이름을 대충 짓게 되는 문제도 있다.

2. 주석 때문에 이름을 대충 짓는 예

// 수면, 마비, 혼란, 석화, 사망 이외의 상황에서 행동 가능
boolean isNotSleepingAndIsNotParalyzedAndIsNotConfusedAndIsNotStoneAndIsNotDead() {
    ...
}

위 코드처럼 주석을 달면, 이후에 행동 불능 상태로 '공포' 등이 추가되었을 때, 주석을 함게 변경해줘야 하고, 주석을 변경했다고 해도 메서드 이름에 '공포'를 나타내는 단어가 들어 있지 않으므로 구현과 이름에 괴리가 생긴다. 이와 같은 메서드는 주석으로 설명을 추가하기보다, 메서드의 이름 자체를 수정하는 것이 좋다.

boolean canAct() {
    if (states.contains(StateType.sleeping) ||
    	states.contains(StateType.paralyzed) ||
        states.contains(StateType.confused) ||
        states.contains(StateType.stone) ||
        states.contains(StateType.dead)) {
    	return false;
    }
}

메서드의 가독성을 높이면, 주석으로 설명을 추가하지 않아도 된다. 그러면 내용이 낡은 주석이 생길 가능성도 줄어든다.

3. 의도와 사양 변경 시 주의 사항을 읽는 이에게 전달하기

한 번 작성된 코드는 유지 보수할 때와 사양을 변경할 때 다시 읽힌다. 각각의 경우에 코드를 읽는 사람이 주의를 기울여야 하는 부분은 아래와 같다.

• 유지 보수할 때 : 이 로직은 어떤 의도를 갖고 움직이는가
• 사양을 변경할 때 : 안전하게 변경하려면 무엇을 주의해야 하는가

따라서 주석은 위와 같은 내용을 담는 것이 좋다.

class Member {
    private final States states;
    
    // 고통받는 상태일 때 true를 리턴
    boolean isPainful() {
        // 이후 사양 변경으로 표정 변화를 일으키는 상태를 추가할 경우
        // 이 메서드에 로직을 추가합니다.
        if (states.contains(StateType.poison) ||
            states.contains(StateType.paralyzed) ||
            states.contains(StateType.fear)) {
            return true;
        }
        return false;
    }
}

4. 정리

지금까지 살펴본 주석을 작성하는 규칙을 정리해보면 아래와 같다.

규칙	이유
로직을 변경할 때는 반드시 주석도 함께 변경한다.	주석을 제대로 변경하지 않으면, 실제 로직과 달라져 주석을 읽는 사람에게 혼란을 준다.
로직의 내용을 단순하게 설명하기만 하는 주석은 달지 않는다.	실질적으로 가독성을 높이지 않고, 주석 유지 보수가 힘들다. 결과적으로 내용이 낡은 주석이 될 가능성이 높다.
가독성이 나쁜 로직에 설명을 추가하는 주석은 달지 않는다. 대신 로직의 가독성을 높여야 한다.	주석 유지 보수가 힘들고, 갱신되지 않아 낡은 주석이 될 가능성이 높다.
로직의 의도와 사양을 변경할 때 주의할 점을 주석으로 달아야 한다.	유지 보수와 사양 변경에 도움이 된다.

5. 문서 주석

프로그래밍 언어에 따라 문서 주석 기능을 제공하는 경우도 있다. 자바에는 Javadoc이 있다. JavaDoc의 형식과 태그에 맞춰서 주석을 작성하면, IDEA 등에서 자동으로 API 문서를 생성해주는 기능을 사용할 수 있고, 에디터 위에 커서를 놓으면 주석 내용이 팝업으로 표시되는 등 여러 장점이 있다.

class Money {
    ...
    /**
    * 금액을 추가합니다.
    *
    * @param other 추가 금액
    * @return 추가 후의 금액
    * @throws IllegalArgumentException 통화 단위가 다르면 발생
    */
    Money add(final Money other) {
        if (!currency.equals(other.currency)) {
            throw new IllegalArgumentException("통화 단위가 다릅니다.");
        }
        int added = amount + other.amount;
        return new Money(added, currency);
    }
}

• @param : 매개 변수 설명
• @throw : throw 되는 예외 설명
• @return : 리턴 값 설명

IntelliJ IDEA의 메뉴에서 Tools > Generate JavaDoc을 선택하면, API 문서를 html로 출력할 수 있다.