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

 

앞서 다른 아이템에서도 살펴봤지만 

public으로 공개 API를 만들어버리면 어디로 튈지? 모르기 때문에 설명을 달아줘야 한다고 했다.

 

🤔 문서화 주석은 뭐고 JavaDoc은 뭘까? 

소스 코드에 /** ... */ 형식으로 주석을 다는 걸 문서화 주석이라고 하고,

이 문서화 주석을 사용해서 문서를 생성하는 게 JavaDoc이라는 툴이다.(javac 컴파일러가 아님)

 

문서화 주석 위치 

클래스, 인터페이스, 생성자, 메서드, 필드의 선언 바로 앞에 작성한 것만 인식한다.

import 앞에 주석을 작성하면 클래스에 대한 주석이라고 인식하지 못한다.

 

문서화 주 유의 사항 

✅ 유지 보수까지 고려한다면 공개된 클래스, 인터페이스, 메서드, 필드 선언에도 문서화 주석을!

    문서화 주석이 없다면 JavaDoc도 그저 공개 API 요소들의 선언만 나열해 주는 게 전부다.

    공개 클래스의 기본 생성자에 주석을 달 수 있는 방법이 없으니 절대 기본 생성자를 사용하면 안 된다.

    문서가 잘 갖춰지지 않은 API는 쓰기 헷갈려서 오류의 원인이 되기 쉽다.

✅ 메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술!

    메서드가 어떻게 동작하는지를 적는 게 아니라 무엇을 하는지 기술해야 한다.(how가 아닌 what!)

    클라이언트가 해당 메서드를 호출하기 위한 전제조건(precondition)을 모두 나열해야 한다.

    메서드가 성공적으로 수행된 후에 만족해야 하는 사후조건(postcondition)도 모두 나열해야 한다.

    부작용(사후조건으로 명확하게 나타나지는 않지만 시스템의 상태에 어떠한 변화를 가져오는 것)도 문서화할 것

 

*부작용이란 사후조건으로 명확히 나타나지는 않지만 시스템의 상태에 따라 어떠한 변화를 가져오는 것을 의미

 

JavaDoc에서 사용되는 태그들 

https://velog.io/@ming/JavaDoc-%EC%A3%BC%EC%84%9D-%EC%95%8C%EA%B3%A0%EC%93%B0%EC%9E%90

JavaDoc 주석 알고쓰자!

 

 

문서화 주석에도 표준 규약이 있으며 그 규칙은 다음과 같다.

 

✅메서드 문서화 주석 규칙 

모든 매개변수에 @param 태그

반환 타입이 void가 아니라면 @return 태그

발생할 가능성이 있는 모든 예외(검사/비검사)에는 @thorw 태그

 

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

 

@code는 태그로 감싼 내용을 코드용 폰트로 렌더링 하며,

감싼 내용에 포함된 HTML 요소나 다른 자바독 태그를 무시하는 역할을 한다.

여러 줄로 된 코드 예시를 넣으려면 <pre>{@code ...}</pre> 형태로 쓰면 된다.

 

✅상속용 클래스 문서화 주석 규칙 

클래스를 상속용으로 설계할 때는, 

@implSpec 을 사용해 자기 사용 패턴을 문서로 남겨 메서드를 올바르게 재정의하는 방법을 알려줘야 한다.

 

@impleSpec
해당 메서드와 하위 클래스 사이의 계약을 설명
하위 클래스들이 그 메서드를 상속하거나 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;
    }

 

✅제네릭 타입 문서화 주석 규칙 

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

/**
* 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();
}

 

문서화 주석의 검색 기능

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

클래스, 메서드, 필드 같은 API 요소의 색인은 자동으로 만들어지며 원한다면 

{@Index} 태그를 사용해 API에서 중요한 용어를 추가로 색인화할 수 있다.

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

 

🤔 API 설명에 <, >, & 등의 HTML 메타문자를 포함시키고 싶다면?

{@literal} 태그로 감싸는 것이다.

이 태그는 HTML 마크업이나 자바독 태그를 무시하게 해 준다..

앞서 본 {@code} 태그와 비슷하지만 코드 폰트로 렌더링 하지는 않는다.

 A geometric series converges if {@literal |r| < 1}.

이 주석은 "A geometric series converges if |r| < 1."로 변환된다.

< 기호만 {@literal}로 감싸도 결과는 똑같지만, 그렇게 하면 코드에서의 문서화 주석을 읽기 어려워진다.

 

문서화 주석은 코드에서건 변환된 API 문서에서건 읽기 쉬워야 한다는 게 일반 원칙이다.

양쪽을 만족하지 못하겠다면 API 문서에서의 가독성을 우선하자!

 

 

JavaDoc 문서 출력(인텔리제이)

https://log-laboratory.tistory.com/306

[Intellij] JavaDoc 주석 + 파일 생성

 

 

정리

공개 API라면 모두 설명을 달아야 하며, 표준 규약을 일관되게 지키자!

문서화 주석에 임의의 HTML 태그 사용이 가능하다!

 단, HTML 메타문자는 특별하게 취급해야 한다.