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

2021-07-23

문서화

API를 쓸모 있게 하려면 잘 작성된 문서도 있어야 한다.

자바독이라는 유틸리티를 사용하면 코드가 변경되어도 문서를 자동으로 변경을 해준다.

자바독은 소스코드 파일에서 문서화 주석이라는 특수한 형태로 기술된 설명을 추려 API 문서로 변환해 준다.

문서화 주석을 작성하는 규칙은 공식 언어 명세에 속하진 않지만 자바 프로그래머라면 알아야 하는 표준 API라고 할 수 있다.

이 규칙은 문서화 주석 작성법(How to Write Doc Comments) 웹페이지에 기술 되어 있다.

주석

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

직렬화 할 수 있는 클래스라면 직렬화 형태에 관해서도 적어야 한다.

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

유지보수까지 고려한다면 대다수의 공개되지 않은 클래스, 인터페이스, 생성자, 메서드, 필드에도 문서화 주석을 달면 좋다.

좋은 주석

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

  • 상속용으로 설계된 클래스의 메서드가 아니라면 그 메서드가 어떻게(how) 동작하는지가 아니라 무엇(what)을 하는지 기술해야 한다.
  • 클라이언트가 메서드를 호출하기 위한 전제조건을 모두 나열해야 한다
  • @throws 태그로 비검사 예외를 선언하여 암시적으로 기술한다.
  • 메서드가 성공적으로 수행된 후에 만족해야 하는 사후조건도 모두 나열해야 한다.
  • 전제조건과 사후조건뿐만 부작용도 문서화 해야 한다.
    • 부작용이란 사후조건으로 명확히는 나타나지는 않지만 시스템의 상태에 어떠한 변화를 가져오는 걸 뜻함 ex ) 백그라운드 스레드를 시작시키는 메서드
  • 클래스 혹은 정적 메서드가 스레드 안전하든 아니든, 스레드 안전 수준을 반드시 포함해야 한다
  • 직렬화 할 수 있는 클래스라면 직렬화 형태도 API 설명에 기술해야 한다.

메서드의 계약을 완벽히 기술하려면 모든 배개변수에 @param 태그를, 반환타입이 void가 아니라면 @return 태그를, 발생할 가능성이 있는 모든 예외에 @throws 태그를 달아야 한다.

@return 태그의 설명이 메서드 설명과 같을 때 @return 태그를 생략해도 된다.

주석 서술

  • @param,@return 태그의 설명은 매개변수가 뜻하는 값이나 반환값을 설명하는 명사구를 쓴다. 드물게 명사구 대신 산술 표현식을 쓰기도 한다.
  • @throws 태그의 설명은 if로 시작해 해당 예외를 던지는 조건을 설명하는 절이 뒤따른다.
  • 관례상 @param, @return @throws 태그의 설명에는 마침표를 붙이지 않는다.
// Positional Access Operations

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

HTML 태그와 어노테이션

자바독 유틸리티는 문서화 주석을 HTML로 변환하므로 문서화 주석 안의 HTML 요소들이 최종 HTML 문서에 반영 된다.

@code

  • 이 태그로 감싼 내용을 코드용 폰트로 렌더링 한다.
  • 태그로 감싼 내용에 포함된 HTML 요소나 다른 자바독 태그를 무시 한다.

문서화 주석에 여러 줄로 된 코드 예시를 넣으려면 {@code} 태그를 다시 <pre> 태그로 감싸면 된다.

이렇게 하면 HTML의 탈출 메타문자를 쓰지 않아도 코드의 줄바꿈이 그대로 유지된다.

단, @ 기호에는 무조건 탈출문자를 붙여야 한다.

@implSpec

클래스를 상속용으로 설계할 때는 자기사용 패턴에 대해서도 문서에 남겨 다른 프로그래머에게 그 메서드를 올바로 재정의하는 방법을 알려줘야 한다.

자기사용 패턴(self-use pattern)

한 메소드가 같은 클래스 내의 다른 메서드를 사용하는 패턴

자기사용 패턴은 자바 8에 추가된 @implSpec 태그로 문서화 한다.

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

/**
*	Return true if this Collection is empty.
*
* @implSpec
* This implementation returns {@code this.size() == 0}.
*
* @return true if this collection is empty 
*/

자바 11까지도 자바독 명령줄에서 -tag "implSpec:a:Implementation Requirements:" 스위치를 켜주지 않으면 @implSpec 태그를 무시한다.

@literal

API 설명에 <, >, & 등의 HTML 메타문자를 포함시키려면 특별한 처리를 해줘야 하는데, 가장 좋은 방법은 {@literal} 태그로 감싸는 것이다.

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

* {@literal |r| < 1}이면 기하 수열이 수렴한다.
이 주석은 **” r < 1이면 기하 수열이 수렴한다.”** 로 변환된다.

사실 < 기호만 {@literal}로 감싸도 결과를 똑같지만, 코드에서 가독성을 위해서 이렇게 사용 했다.

@index

자바 9부터는 자바독이 생성한 HTML 문서에 검색 기능이 추가되어 광대한 API 문서들을 누비는 일이 한결 수월해졌다.

API 문서 페이지 오른쪽 위에 있는 검색창에 키워드를 입력하면 페이지들이 드롭다운 메뉴로 나타난다.

클래스, 메서드, 필드 같은 API 요소의 색인은 자동으로 만들어지며, 원한다면 {@index} 태그를 사용해 API 중요한 용어를 추가로 색인화할 수 있다.

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

@inheritDoc

이 태그를 사용하면 문서화 주석 일부를 상속할 수 있다.

주석 문장 구조

  • 첫 번째 문장은 해당 요소의 요약 설명을 쓴다.

    • 요약 설명은 반드시 대상의 기능을 고유하게 기술해야 한다.

    • 다중정의된 메서드들의 설명은 같은 문장으로 시작하는게 자연스럽겠지만 문서화 주석에서는 허용되지 않으니 주의하자.

    • 처음으로 마침표가 나오는 곳이 요약설명의 끝이다.

      • 마침표가 필요하면 {@literal} 로 감싸주자.

    • 메서드와 생성자의 요약설명은 해당 메서드와 생성자의 동작을 설명하는 주어가 없는 동사구여야 한다.

      • ArrayList(int initialCapacity) : 지정한 초기 용량을 갖는 빈 리스트를 생성한다.

    • 영어에서는 2인칭이 아닌 3인칭 문자으로 써야한다.

제너릭,열거타입,어노테이션

  • 제너릭 타입이나 제너릭 메서드를 문서화할 때는 모든 타입 매개변수에 주석을 달아야 한다.
  • 열거 타입을 문서화 할때는 상수들에도 주석을 달아야 한다.
    • 열거 타입 자체와 그 열거 타입의 public 메서드에도 달아야 한다.
    • 설명이 짧으면 한 문장으로 써도 된다.
  • 어노테이션 타입을 문서화할 때는 멤버들에도 모두 주석을 달아야 한다.

패키지와 모듈

  • 패키지를 설명하는 문서화 주석은 package-info.java 파일에 작성한다.
    • 이 파일은 패키지 선언을 반드시 포함해야 하며 패키지 선언 관련 어노테이션을 추가로 포함할 수 있다.
  • 모듈 시스템은 module-info.java 파일에 작성하면 된다.

자바독 문서 검증

자바독은 프로그래머가 자바독 문서를 올바르게 작성했는지 확인하는 기능을 제공한다.

자바7에서는 명령줄에서 -Xdoclint 스위치를 켜주면 활성화 되고, 자바 8부터는 기본으로 작동한다.

체크스타일 같은 IDE 플러그인을 사용하면 더 완벽하게 검사 된다.

자바독이 생성한 HTMl 파일을 HTML 유효성 검사기로 돌리면 문서화 주석의 오류를 한층 더 줄일 수 있다.

HTML 유효성 검사기는 잘못 사용한 HTML 태그를 찾아준다.

자바9와 10의 자바독은 기본적으로 HTML4.01 문서를 생성하지만, 명령줄에서 -html5 스위치를 켜면 HTML5로 만들어 준다.