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

Javadoc

• 전통적으로 API문서는 사람이 직접 작성하므로 코드가 변경되면 매번 함께 수정해줘야 하는데, 자바에서는 자바독(javadoc)이라는 유틸리티가 그러한 기능을 도와준다.

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

• 문서화 주석을 작성하는 규칙은 공식 언어 명세에 속하진 않지만 자바 프로그래머라면 알아야 하는 업계 표준 API라 할 수 있다.
• 이 규칙은 문서화 주석 작성법(How to Write Doc Comments) 웹 페이지에 기술되어 있다.
• 자바 4 이후로는 갱신되지 않은 페이지지만 그 가치는 여전하다.

• 자바 버전이 올라가며 추가된 중요한 자바독 태그는 다음과 같다
• 자바5 > @literal, @code
• 자바8 > @code, @implSpec
• 자바9 > @index

🎨  Javadoc 태그

• @param : 매개변수가 뜻하는 명사구, 모든 매개변수의 설명을 작성한다.

• @return : 반환 값을 설명하는 명사구, 반환 타입 void를 제외하고 설명을 작성한다.

• @throws : 예외를 던지게 되는 조건 설명을 작성한다.

• {@code} : 주석 내에 HTML 요소나 다른 자바독 태그를 무시한다.
• 주석에 코드를 여러줄을 추가하려면 <pre>{@code 코드~~~}</pre> 형태로 작성한다.

• {@literal} : 주석 내에 HTML 요소나 다른 자바독 태그를 무시한다.
• <, >, &등의 HTML 메타문자를 포함시킨다.
• code와 비슷할 수 있지만 코드 폰트로 랜더링을 안한다.

• @implSpec : 해당 메서드와 하위 클래스 사이를 계약을 설명한다.
• 하위 클래스들이 메서드를 상속하거나 super 키워드를 이용해 호출할 때 메서드가 어떻게 동작하는지 명확하게 인지할 수 있도록 해준다.

• {@inheritDoc} : 상위 타입의 문서화 주석 일부를 상속할 수 있다.

📚  javadoc 사용법

javadoc -d docs {file_name}

# 한글을 사용할 경우에는 UTF-8로 인코딩이 필요합니다.
javadoc -d docs *.java -encoding UTF-8 -charset UTF-8 -docencoding UTF-8

🧐  javadoc 작성 시 유의사항

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

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

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

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

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

• 상속용으로 설계된 클래스의 메서드가 아니라면? 무엇을 하는지를 기술해야 한다.

• 즉 how가 아닌 what을 기술해야 한다.

• 문서화 주석에는 클라이언트가 해당 메서드를 호출하기 위한 전제조건을 모두 나열해야 한다.

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

• 일반적으로 전제조건은 @thorws 태그로 비검사 예외를 선언하여 암시적으로 기술한다.

• 전제조건과 사후조건 뿐만 아니라 부작용도 문서화 해야한다.
• 부작용이란 사후조건으로 명확히 나타나지는 않지만 시스템의 상태에 어떤 변화를 가져오는 것을 뜻한다.

• 메서드의 계약(contract)
• 완벽하게 기술하기 위해 모든 매개변수에 @param 태그를 명시해야 한다.
• 반환타입이 void가 아닐 경우엔 @return 태그를 꼭 명시해야 한다.
• 발생할 가능성이 있는 모든 예외에는 @throws 태그를 명시해야 한다.

3️⃣  클래스 상속용으로 설계 시 문서화 작성

• 자기사용 패턴(self-use pattern)에 대해 문서에 남겨 다른 개발자에게 그 메서드를 올바르게 재정의 할 수 있도록 방법을 명시해줘야 한다.

• 자바8에 추가된 @implspec 태그로 문서화를 해야한다.

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

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

4️⃣ API 문서 가독성

• 각 문서화 첫번째 문장은 해당 요소의 요약 설명으로 간주된다.

• 요약 설명은 대상의 기능을 고유하게 기술해야 한다.
• 헷갈리지 않으려면 한 클래스 안에서 요약 설명이 똑같은 멤버(혹은 생성자)가 둘 이상이면 안됨

• 다중정의된 메서드가 있는 경우 각 메서드들의 설명은 같은 문장으로 시작하는게 자연스럽겠지만, 문서화 주석에서는 허용하지 않음

• 요약 설명에서는 마침표(.)에 주의해야 한다.
• 요약 설명이 끝나는 판단 기준은 처음에 발견되는 {<마침표><공백><다음문장시작>} 패턴의 <마침표> 까지이다.
• 여기서 <공백>은 스페이스, 탭, 줄바꿈, 첫번째 블록 태그이다.
• <다음문장시작>은 소문자가 아닌 문자이다.

• 가장 좋은 해결책은 의도하지 않는 마침표를 포함한 텍스트를 {@literal}로 감싸주는 것이다.

/**
 * A suspect, such as Colonel Mustard  or {@literal Mrs. Peacock}
 */
public class Suspect {}

// 자바 10부터는 @{summary}라는 요약 태그가 추가되어 깔끔하게 처리할 수 있음

/**
 * {@summary A suspect, such as Colonel Mustard or Mrs. Peacock.}
 */
public enum Suspect {}

5️⃣  제네릭 타입 문서화

• 제네릭 타입은 모든 타입 매개변수에 주석을 달아야 한다.

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

6️⃣  열거타입 문서화

• 상수들에도 주석을 작성해야 한다.

• 열거타입 자체와 그 열거 타입의 public 메서드도 주석을 작성해야 한다.

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

7️⃣  애노테이션 타입 문서화

• 필드, 멤버들에도 모두 주석을 달아야 한다.

• 필드 설명은 명사구로 작성하며 타입의 요약 설명은 프로그램 요소에 이 애노테이션을 사용한다는 것이 어떤 의미인지 동사구로 작성한다.

/**
 * 이 애너테이션이 달린 메서드는 명시한 예외를 던져야만 성공하는
 * 테스트 메서드임을 나타낸다.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
    /**
     * 이 애너테이션을 단 테스트 메서드가 성공하려면 던져야 하는 예외,
		 * (이 클래스의 하위 타입 예외는 모두 허용된다.) 
     */
    Class<? extends Throwable> valueO;
}

8️⃣  API 문서화에서 자주 누락되는 두가지 설명을 포함하자

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

• 직렬화 할 수 있는 클래스라면 직렬화 형태도 API 설명에 기술해야 한다.

🧑🏻‍⚖️  결론

• 문서화 주석은 API를 문서화하는 가장 훌륭하고 효과적인 방법이며 공개 API라면 빠짐없이 설명을 작성해야 한다.

• 표쥰 규악을 일관되게 지키자.

• 문서화 주석에 임의의 HTML 태그를 사용할 수 있음을 기억하고 단 HTML 메타문자는 특별하게 취급해야 한다.