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

[corock]

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

국내 개발자 센터

• 네이버 개발자 센터 - NAVER Developers
• Kakao Developers
• LINE Developers
• 쿠팡 Open APIs

공개 API 명세 예시

• NAVER Developers > 네이버 로그인 > API 명세

Javadoc?

소스 코드 파일에서 문서화 주석(doc comment; 자바독 주석)이라는 특수한 형태로 기술된 설명을 추려 API 문서로 변환해주는 유틸리티

핵심 정리

• API 를 올바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석(/** (...) */)을 달아야 합니다.
• 직렬화할 수 있는 클래스라면 직렬화 형태(아이템 87. 커스텀 직렬화 형태를 고려해보라)에 관해서도 적어야 합니다.
• 문서가 잘 갖춰지지 않은 API 는 쓰기 헷갈려서 오류의 원인이 되기 쉽습니다.
• 기본 생성자에는 문서화 주석을 달 방법이 없으니 공개 클래스는 절대 기본 생성자를 사용하면 안 됩니다.
• 유지보수까지 고려한다면 대다수의 공개되지 않은 클래스, 인터페이스, 생성자, 메서드, 필드에도 문서화 주석을 달아야 합니다.

Javadoc 기본 사용법

공통

• 문서화 주석을 사용하는 첫 문장은 항상 마침표로 끝나야 합니다.
• 문서화 주석은 Javadoc 에 의해 HTML 로 변환하므로 HTML 태그를 사용할 수 있습니다.

메서드

not "how" but "what"

• 메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 합니다.
  • 그 메서드가 어떻게(how) 동작하는지가 아니라 무엇을(what) 하는지를 기술해야 합니다.
• 문서화 주석에는 클라이언트가 해당 메서드를 호출하기 위한 전제조건과 사후조건, 부작용을 모두 나열해야 합니다.
• 관례상 @param 태그와 @return 태그 설명은 해당 매개변수가 뜻하는 값이나 반환 값을 설명하는 명사구를 사용합니다.
• 관례상 @param, @return, @throws 태그의 설명에는 마침표를 붙이지 않습니다.
  • 하지만, 한글로 작성할 경우 온전한 종결 어미로 끝나면 마침표를 써주는 게 일관된 모습입니다.

전제조건(precondition)

사후조건(postcondition)

예시

아래 예시는 위에서 소개한 문서화 주석 규칙을 모두 적용한 예시로, List 인터페이스의 get(..) 메서드입니다.

java.util.List.java

public interface List<E> extends Collection<E> {

    // (...)

    /**
     * Returns the element at the specified position in this list.
     *
     * @param index index of the element to return
     * @return the element at the specified position in this list
     * @throws IndexOutOfBoundsException if the index is out of range
     *         ({@code index < 0 || index >= size()})
     */
    E get(int index);

    // (...)

}

List.java 한글 패치 버전

public interface List<E> extends Collection<E> {

    // (...)

    /**
     * 이 리스트에서 지정한 위치의 원소를 반환한다.
     * <p>
     * 이 메서드는 상수 시간에 수행됨을 보장하지 <i>않는다</i>. 구현에 따라 원소의 위치에 비례해 시간이 걸릴 수도 있다.
     *
     * @param index 반환할 원소의 인덱스; 0 이상이고 리스트 크기보다 작아야 한다.
     * @return 이 리스트에서 지정한 위치의 원소
     * @throws IndexOutOfBoundsException 인덱스가 범위를 벗어나면, 즉, ({@code index < 0 || index >= size()}) 이면 발생한다.
     */
    E get(int index);

    // (...)

}

주요 Javadoc 태그 목록

• @param: 특정 메서드 조건에 영향받는 매개변수를 기술할 때 사용
• @return: 특정 메서드의 반환 타입이 void 가 아닐 경우 기술
• @throws: 비검사 예외(unchecked exception)가 있을 때 사용
• @code: HTML 렌더링 시 코드 폰트로 변환
• @inheritDoc: 상위 타입의 문서화 주석 일부를 상속 가능
• @literal (>= Java 1.5): Javadoc 첫 문장에서 필요 시 사용
• @summary (>= Java 10): Javadoc 에서 요약 전용 태그
• @implSpec (>= Java 8): 해당 메서드와 하위 클래스 사이의 계약 설명
• @index (>= Java 9)
• @link
• @see

Javadoc 태그 상세

@param

• 전제조건(precondition)에 영향받는 매개변수에 붙임
• 모든 매개변수에 붙이는 것을 권장
• 관례상 명사구로 쓰고, 마침표를 붙이지 않음

@return

• 자체 코딩 표준에서 @return 태그 설명이 메서드 설명과 같으면 생략 가능
• 관례상 명사구로 쓰고, 마침표를 붙이지 않음

@throws

• 비검사 예외(unchecked exception)가 있을 시 선언
• 비검사 예외 하나당 전제조건(precondition) 한 개 연결
• 관례상 마침표를 붙이지 않음

{@code (...)}

• @code Javadoc 태그로 감싼 내용을 HTML 렌더링 시 코드용 폰트로 바꿔줌
• 태그로 감싼 내용에 포함된 HTML 요소나 다른 Javadoc 태그 무시
• <pre>{@code (...)}</pre> 처럼 사용하면 여러 줄로 된 코드 작성 가능
  • 단, @ 사용 시 탈출 문자를 붙여야 함

{@literal (...)}

• <, >, & 등의 HTML 메타 문자를 포함할 때 사용
• {@code (...)} 와 형태가 비슷하나 코드 폰트로 렌더링하지 않음
• Javadoc 첫 문장은 주로 요약 설명에 해당
• 하나의 클래스 또는 하나의 인터페이스 안에 요약 설명이 중복되면 안됨
• 마침표 주의!
  • 다음 문서화 주석은 ~ Mr. 까지 요약 설명으로 간주

    /**
     * A suspect, such as Colonel Mustard or Mr. CoRock.
     */
    public enum Suspect {
        // (...)
    }

  • 이 경우 @literal 로 문장을 감싸줌으로써 해결 가능

    /**
     * A suspect, such as Colonel Mustard or {@literal Mr. CoRock}.
     */
    public enum Suspect {
        // (...)
    }

@summary

• 문서화 주석에서 요약에 해당하는 부분을 깔끔하게 처리 가능

/**
 * {@summary A suspect, such as Colonel Mustard or {@literal Mr. CoRock}.
 */
public enum Suspect {
    // (...)
}

@implSpec

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

/**
 * 이 컬렉션이 비었다면 true 를 반환한다.
 *
 * @implSpec
 * 이 구현은 {@code this.size() == 0} 의 결과를 반환한다.
 *
 * @return 이 컬렉션이 비었다면 true, 그렇지 않으면 false
 */
public boolean isEmpty() {
    // (...)
}

@index

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

/** 이 메서드는 {@index IEEE 754} 표준을 준수한다.

회고

핵심 정리 편에서

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

히스토리가 있는 API 작업을 이어 받았을 때 문서의 유무가 소요 시간에 큰 영향을 끼치는 것 같습니다.

이외에도

• 경어체를 사용하지 않는 태그도 존재하는 점을 이번 아이템을 통해 알았습니다.
• 아직 손에 익지 않는 다른 문서화 주석 태그도 적극적으로 사용해보려고 의식해야겠다고 마음먹었습니다.
• 어릴 때 국어를 잘했으면 오늘날 좀 더 도움이 되지 않았을까? 라고 생각해봤습니다.

[JoisFe]

여러 기업들의 예시 좋았습니다.!!

[Irisation23]

경어체 사용해서 팀장님께 깨졌습니다.

참조자료로 해당 링크 참조해서 보내면 될까요?