Doc Comment

2024. 3. 7.

hyoguoo

Backend Engineer

공개된 API 요소에는 항상 문서화 주석을 작성하라

공개된 API를 올바로 문서화하기 위해선 아래의 요건들을 충족해야 한다.

공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다.
직렬화 가능 클래스라면 직렬화 형태에 관해서도 문서화해야 한다.
스레드 안전하든 안하든 스레드 안전 수준을 명시해야 한다.
유지보수까지 고려한다면 공개되지 않은 클래스, 인터페이스, 생성자, 메서드, 필드에도 간략하게나마 문서화 주석을 달아두는 것이 좋다.
기본 생성자에는 문서화 주석을 달 수 없으니 기본 생성자를 사용하면 안된다.
첫 번째 문장은 요약 설명으로 간주되기 때문에 대상의 기능을 고유하게 기술해야 한다.

메서드 문서화 주석

특히 메서드 문서화 주석은 해당 메서드와 클랑리언트 사이의 규약을 명료하게 기술해야 한다.

어떻게(how)가 아닌 무엇(what)을 하는지를 기술
클라이언트가 메서드를 호출하기 위한 전제조건(precondition) 기술
- 일반적으로 @throws 태그로 비검사 예외를 선언하여 암시적으로 기술
메서드 수행 후 만족해야 하는 사후조건(postcondition)을 기술
부시스템의 상태에 영향을 미치는 경우 부작용(side effect)을 기술
@param, @return 태그 사용하여 메서드의 매개변수와 반환값 기술
- 관례상 해당 매개변수가 뜻하는 값이나 반환값의 의미를 간략하게 기술
@throws 태그 사용하여 메서드가 던질 수 있는 모든 예외 기술(검사/비검사 모두)

위 규칙을 지킨 문서화 주석 예시는 아래와 같다.

class Example {
    /**
     * 이 리스트에서 지정한 위치의 원소를 반환한다.
     *
     * <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.
     * <p>이 메서드는 상수 시간에 수행됨을 보장하지 <i>않는다</i>. 구현에 따라
     * 원소의 위치에 비례한 시간이 걸릴 수도 있다.
     *
     * @param  index 반환할 원소의 인덱스; 0 이상이고 리스트 크기보다 작아야 한다.
     * @return 이 리스트에서 지정한 위치의 원소
     * @throws IndexOutOfBoundsException index 범위를 벗어나면,
     *         ({@code index < 0 || index >= this.size()})이면 발생한다.
     */
    E get(int index);
}
// `{@code ...}` 태그는 코드를 인라인으로 포함시키는 태그로, 코드를 인용하는 것과 같은 효과를 내는데, 코드용 폰트로 렌더링해주면서 HTML 특수문자나 다른 자바독 태그를 무시해준다.
// 비슷한 태그로 `{@literal ...}` 태그가 있는데, 이는 HTML 특수문자를 무시해주는 효과만 있고 코드용 폰트로 렌더링해주지는 않는다.

그 외에 특수한 문서화 주석

그 외에 제네릭 타입, 열거 타입, 애너테이션 타입을 문서화할 때는 추가적인 주석을 달아야 한다.

제네릭 타입 : 모든 타입 매개변수
열거 타입 : 모든 상수
애너테이션 타입 : 모든 멤버

Java