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

Javadoc 자바독 16가지 설명

자바독은 소스코드 파일에서 문서화 주석(doc comment; 자바독 주석)이라는 특수한 형태로 기술된 설명을 추려 API 문서로 변환해준다. 문서화 주석을 작성하는 규칙은 공식 언어 명세에 속하진 않지만 자바 프로그래머라면 알아야하는 업계 표준 API다. 아래의 유의점을 보자.

 

1) 개발한 API를 올바르게 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야한다.

직렬화할 수 있는 클래스라면 적렬화 형태에 관해서도 적어야한다. 문서화 주석이 없다면 자바독도 그저 공개 API 요소들의 '선언'만 나열해주는 게 전부다. 문서가 잘 갖춰지지않은 API는 쓰기 헷갈려서 오류의 원인이 되기 쉽다. 

 

2) 메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야한다. 

그 메서드가 어떻게 동작하는지(how)가 아닌 무엇을 하는지(what)를 기술해야한다. 또한 메서드가 성공적으로 수행된 후에 만족해야하는 사후조건(postcondition)도 모두 내열해야한다. @param 태그를 사용하여 그 조건에 영향받는 매개변수에 기술할 수도 있다.

 

3) 부작용 또한 문서화해야한다.

부작용이란, 시스템의 상태에 어떠한 변화를 가져오는 것으로 예를들어 백그라운드 스레드를 시작시키는 메서드라면 그 사실을 문서에 밝혀야한다.

 

4) 모든 매개변수에 @param 태그를, 반환 타입이 void가 아니라면 @return 태그를, 발생할 가능성이 있는 모든 예외에 @throws 태그를 달아야한다. 

/**
     ...
     * @param <T> the component type of the array to contain the collection
     * @param generator a function which produces a new array of the desired
     *                  type and the provided length
     * @return an array containing all of the elements in this collection
     * @throws ArrayStoreException if the runtime type of any element in this
     *         collection is not assignable to the {@linkplain Class#getComponentType
     *         runtime component type} of the generated array
     * @throws NullPointerException if the generator function is null
     * @since 11
     */
    default <T> T[] toArray(IntFunction<T[]> generator) {
        return toArray(generator.apply(0));
    }

 

5) {@code} 태그를 사용하면 html 메타문자인 < 기호 등을 별다른 처리 없이 바로 사용할 수 있다.

/**
* Returns {@code true} if this list contains no elements.
*
* @return {@code true} if this list contains no elements
*/
boolean isEmpty();

 

6) @implSpec 주석은 해당 메서드와 하위 클래스 사이의 계약을 설명하여, 하위 클래스들이 그 메서드를 상속하거나 super 키워드를 이용해 호출할때 그 메서드가 어떻게 동작하는지를 명확히 인지하고 사용하도록 해줘야한다.

/**
* @implSpec
* this implementation returns {@code this.size() == 0}.

* @return true if this collection is empty
*/
public boolean isEmpty() { ... }

 

7) {@literal}

해당 태그는 HTML 마크업이나 자바독 태그를 무시하게 해준다. {@code}와 비슷하지만 코드 폰트로 렌더링하지 않는다. 

/**
* A geometric series converges if {@literal |r| < 1}.
...
*/
public void test();

 

8) 자바 10부터는 {@summary}라는 요약 설명 전용 태그가 추가되었다.

요약 설명이 문서화 주석의 첫 문장이 아니다. 메서드와 생성자의 요약 설명은 해당 메서드와 생성자의 동작을 설명하는 (주어가 없는) 동사구여야 한다.

 

9) {@index}를 사용하여 검색(색인) 기능을 추가할 수 있다.

/**
* This method complies with the {@index IEEE 754} standard.
...
*/
public void test();

 

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

/**
...
 * @param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
*/
public interface Map<K, V> { ... }

 

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

/**
 * 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
}

 

12) 어노테이션 타입을 문서화할때는 멤버들에도 모두 주석을 달아야한다.

13) 클래스 혹은 정적 메서드가 스레드 안전하든 그렇지 않든, 스레드 안전 수준을 반드시 API 설명에 포함해야 한다. 

14) 자바독은 메서드 주석을 '상속' 시킬 수 있다.

문서화 주석이 없는 API 요소를 발견하면 자바독이 가장 가까운 문서화 주석을 찾아준다. 이때 상위 '클래스'보다 그 클래스가 구현한 '인터페이스'를 먼저 찾는다.

 

15) {@inheritDoc} 태그를 사용하여 상위 타입의 문서화 주석을 일부 상속할 수 있다.

16) 문서화 주석이 부족하고, 별도의 설명이 필요할때는 관련 설명 문서가 존재할 경우 그 문서의 링크를 주석에 제공하자.