공개된 API에는 문서화 주석을 달자
API를 올바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다. 직렬화할 수 있는 클래스라면 직렬화 형태에 관해서도 적어야 한다.
메서드용 문서화 주석
- 메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다. 어떻게 동작하는지가 아닌, 무엇을 하는지를 기술해야 한다.
- 문서화 주석에는 클라이언트가 해당 메서드를 호출하기 위한 전제조건을 모두 나열해야 한다.
- 일반적으로 전제조건은 @throws 태그로 비검사 예외를 선언하여 암시적으로 기술한다.
- @param 태그를 이용해 그 조건에 영향받는 매개변수에 기술할 수도 있다.
- 메서드가 성공적으로 수행된 후에 만족해야 하는 사후조건을 나열해야 한다.
- 부작용도 문서화해야 한다. 사후조건으로 명확히 나타나지는 않지만 시스템의 상태에 어떠한 변화를 가져오는지 명시한다.
- e.g ) 백그라운드 스레드를 시작시키는 메서드라면 그 사실을 문서에 밝혀야 한다.
- 클래스를 상속용으로 설계할 때는 자기사용 패턴에 대해서도 문서에 남겨 다른 프로그래머에게 그 메서드를 올바로 재정의하는 방법을 알려줘야 한다.
- @implSpec 태그를 이용하여 문서화 한다.
/**
* @implSpec
* This implementation return {@code this.size() == 0}.
*/참고
- 관례상 @param, @return, @throws 태그의 설명에는 마침표를 붙이지 않는다.
- 자바독은 문서화 주석을 HTML로 변환하므로 문서화 주석 안의 HTML 요소들이 최종 HTML문서에 반영된다.
/**
* <p>이 메서드는 상수 시간에 수행됨을 보장하지 <i>않는다.</i></p>
* @throws java.lang.IndexOutOfBoundsException index가 범위를 벗어나면,
* 즉, ({@code index < 0 || index >= this.size()})이면 발생한다.
*/
E get(int index);- {@code}태그는 태그로 감싼 내용을 코드용 폰트로 렌더링해주며, 태그로 감싼 내용에 포함된 HTML 요소나 다른 자바독 태그를 무시한다.
- API 설명에 <, >, & 등의 HTML 메타문자를 포함시키려면 {@literal} 태그로 감싸자.
{@literal |r| < 1} 이면 기하 수열이 수렴한다. 문서화의 기본 원칙
- 각 문서화 주석의 첫 번째 문장은 해당 요소의 요약 설명으로 간주된다. 요약 설명은 반드시 대상의 기능을 고유하게 기술해야 한다. 헷갈리지 않으려면 한 클래스안에 서 요약 설명이 똑같은
멤버 혹은 생성자가 둘 이상이면 안 된다.- 요약 설명에는 마침표(.)에 주의해야 한다. 마침표까지만 요약 설명이 된다.
- 메서드와 생성자의 요약 설명은 해당 메서드와 생성자의 동작을 설명하는 (주어가 없는) 동사구여야 한다.
- ArrayList(int initialCapacity): Constructs an empty list with the specificied inital capacity
- 클래스, 인터페이스, 필드의 요약 설명은 대상을 설명하는 명사절이어야 한다.
- Instant: An instantaneous point on the time-line
- 제네릭 타입이나 제네릭 메서드를 문서화할 때는 모든 타입 매개변수에 주석을 달아야 한다.
/**
* @param <K> the type of keys maintained by this map
* @param <V> the type of mapped values
*/
public interface Map<K, V> {...}
6. 열거 타입을 문서화할 때는 상수들에도 주석을 달아야 한다.
public enum OrchestraSection {
/** Woodwinds, suc as flute, clarinet and oboe. */
WOODWIND,
}7. 애너테이션 타입을 문서화할 때는 멤버들에도 모두 주석을 달아야 한다. 필드 설명은 명사구로 한다.
8. 스레드 안정성과 직렬화 가능성에 대해 API에 포함하자.