[아이템56] 공개된 API 요소에는 항상 문서화 주석을 작성하라

1. 문서화 주석을 작성하는 규칙

올바르게 API 를 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다. 문서가 잘 갖춰지지 않았다면 사용자가 헷갈려 프로그램 오류의 원인이 되기도 한다. 기본 생성자에는 문서화 주석을 달 방법이 없어, 공개 클래스에는 절대 기본 생성자를 사용하지 말자. 만약, 유지보수까지 고려한다면 공개되지 않은 클래스, 인터페이스, 생성자, 메서드, 필드에도 문서화 주석을 달아야 할 것이다.

1-1. 문서화 주석

메서드라면, 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다. 중요한 것은 어떻게 동작하는지가 아니라, 즉 무엇을 하는지 기술하는 것이다. 또한, 클라이언트가 해당 메서드를 호출하기 위한 전제조건을 모두 나열하고, 성공적으로 수행한 후의 사후조건 또한 모두 나열해야 한다. 뿐만 아니라, 예를 들어 백그라운드 스레드를 시작시키는 메서드라면 이로 인한 부작용도 적어주어야 한다.

매개변수엔 @param 태그를, 반환 타입이 void 가 아니라면 @return 태그를, 예외 케이스에 대해선 @throws 태그를.

아래 예시를 살펴보자. 규칙을 모두 반영한 문서화 주석의 예시이다.

 /**
     * Returns the element at the specified position in this list.  // 요약 설명
     *
     * <p>This method is <i>not</i> guaranteed to run in constant
     * time. In some implementations it may run in time proportional
     * to the element position.
     *
     * @param  index index of element to return; must be
     *         non-negative and less than the size of this list
     * @return the element at the specified position in this list
     * @throws IndexOutOfBoundsException if the index is out of range
     *         ({@code index < 0 || index >= this.size()})
     */
    E get(int index) {
        return null;
    }

각 태그의 쓰임에 대해 살펴보자. @throws 절에는 @code 태그를 사용하여 태그로 감싼 내용을 코드용 폰트로 렌터링하고, 내용에 포함된 HTML 요소나 다른 자바독 태그를 무시할 수 있다.

자기사용 패턴을 위해서는 @implSpec 태그로 문서화하자.

하위 클래스들이 그 메서드를 상속하거나 super 키워드를 이용해 호출할 때, 그 메서드가 어떻게 동작하는지 명확히 인지하고 사용하도록 유도해야 한다. 아래 예시를 살펴보자.

/**
 * Returns true if this collection is empty. // 요약 설명
 *
 * @implSpec This implementation returns {@code this.size() == 0}.
 *
 * @return true if this collection is empty
 */
public boolean isEmpty() {
    return false;
}

@implSpec 태그를 사용해 이 구현은 this.size() == 0 의 결과를 반환한다는 것을 명시해두었다.

 

1-2. 문서화 주석의 특징

각 문서화 주석의 첫 번째 문장은 해당 요소의 요약 설명이다.

예를 들어, "이 리스트에서 지정한 위치의 원소를 반환한다" 와 같이 명확히 기술해야 한다. 또한, 헷갈리지 않기 위해 한 클래스 안에서 요약 설명이 똑같은 멤버가 둘 이상이면 안된다.

요약 설명에서는 마침표(.)에 주의하자.

예를 들어, "머스터드 대령이나 Mrs. 피콕 같은 용의자." 가 요약 설명이면, 첫 번째 마침표가 나오는 곳까지만 요약 설명이 된다. 이를 위한 해결책은, 의도치 않은 마침표를 포함한 텍스트를 {@literal} 로 감싸주면 된다.

/**
 * A suspect, such as Colonel Mustard or {@literal Mrs. Peacock}.
 */
 public class Suspect {...}

자바 9 부터는, HTML 문서에 검색(색인) 기능이 추가되었다.

{@index} 태그를 사용해 아래와 같이 API 에서 중요한 용어를 추가로 색인화할 수 있다.

* This method complies with the {@index IEEE 754} standard.

제네릭 타입이나 제네릭 메서드를 문서화할 때는 모든 타입 매개변수에 주석을 달자.

/**
* An object that maps keys to values. A map cannot contain duplicate keys; each key can map to at most one value.
*
* (Remainder omitted)
*
* @param <K> the type of keys maintained by this map
* @param <V> the type of mapped values
*/
public interface Map<K, V> {...}

열거 타입을 문서화할 때는 상수들에도 주석을 달아야 한다.

/**
* An instrument section of a symphony orchestra.
*/
public enum OrchestraSection {
    /** Woodwinds, such as flute, clarinet, and oboe. */
    WOODWIND,

    /** Brass instruments, such as french horn and trumpet. */
    BRASS,

    /** Percussion instruments, such as timpani and cymbals. */
    PERCUSSION,

   /** Stringed instruments, such as violin and cello. */
    STRING;
}

애너테이션 타입을 문서화할 때는 멤버들에도 모두 주석을 달자.

/**
* Indicates that the annotated method is a test method that
* must throw the designated exception to pass.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
    /**
    * The exception that the annotated test method must throw
    * in order to pass. (The test is permitted to throw any
    * subtype of the type described by this class object.)
    */
    Class<? extends Throwable> value();
}

클래스 혹은 정적 메서드가 스레드 안전하든 안전하지 않든, 스레드 안전 수준을 반드시 API 설명에 포함하자.

주석으로 충분하지 않고 전체 아키텍쳐를 설명해야 할 때에는, 문서의 링크를 제공해주자.

 

2. 결론

다른 사람이 사용할 API 라면 반드시 모든 API 요소를 검토하자. 정말 잘 쓰인 문서인지 확인하는 방버은, 자바독 유틸리티가 생성한 웹페이지를 읽어보는 길뿐이다. 이번 아이템에서 설명한 지침을 잘 따라 API 를 설명하는 깔끔한 문서를 작성하도록 노력해보자.

이러지 말자.