요약
•
API를 문서화 규칙을 잘 지켜서 문서화 주석을 잘 달아두자.
API를 문서화 하는 규칙들
•
API를 올바르게 문서화 하려면, 공개된 모든 클래스와 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다.
◦
문서화 주석이 없다면 자바독을 사용하더라도 공개 API 요소들에 대해 선언만 나열해주는 것이 전부일 뿐이다.
◦
문서가 잘 갖춰지지 않은 API는 쓰기에 헷갈릴 수 있어 오류의 원인이 될 수 있다.
•
메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다.
◦
상속용으로 설계된 클래스의 메서드가 아니라면, 해당 메서드가 어떻게 동작하는지(how)가 아니라 무엇을 하는지(what)를 기술해야 한다.
◦
또한 해당 메서드를 호출하기 위한 전제조건(precondition)과 수행 후 만족되어야하는 사후조건(postcondition)도 모두 나열해야 한다.
◦
그리고 사후조건으로 명확히 나타나지는 않지만 시스템의 상태에 변화를 가져오는 어떤 부작용이라도 전부 문서화 해야한다.
•
메서드의 계약(contact)를 완벽히 기술하기 위해 @param, @return, @throws 태그를 달아 설명하자.
◦
@param과 @return은 보통 명사구를 사용하고, 드물게 산술 표현식을 사용하기도 한다.
◦
@throws는 if로 시작하여 해당 예외를 던지는 조건을 뒤에 설명한다.
◦
세 태그 모두 마침표를 붙이지 않는다.
/**
* 이 리스트에서 지정한 위치의 원소를 반환한다.
*
* <p>이 메서드는 상수 시간에 수행됨을 보장하지 <i>않는다</1>. 구현에 따라
* 원소의 위치에 비례해 시간이 걸릴 수도 있다.
*
* @param index 반환할 원소의 인덱스; 0 이상이고 리스트 크기보다 작아야 한다.
* @return 이 리스트에서 지정한 위치의 원소
* @throws IndexOutOfBoundsException index가 범위를 벗어나면,
* 즉, ({@codeindex < 0 || index >= this.size()})이면발생한다.
*/
Java
복사
•
한 클래스 혹은 인터페이스 안에서 요약 설명이 똑같은 멤버나 생성자가 둘 이상이어서는 안된다.
•
제네릭 타입이나 제네릭 메서드를 문서화 할 때는 모든 타입 매개변수에 주석을 달아야 한다.
/**
* 키와 값을 매핑하는 객체. 맵은 키를 중복해서 가질 수 없다.
* 즉, 키 하나가 가리킬 수 있는 값은 최대 1개다.
*
* (나머지 설명은 생략)
*
* @param <K> 이 맵이 관리하는 키의 타입
* @param <V> 매핑된 값의 타입
*/
public interface Map<K, V> { ... }
Java
복사
•
열거 타입을 문서화 할 때는 상수들에도 모두 주석을 달아야 한다.
/**
* 심포니 오케스트라의 악기 세션.
*/
public enum OrchestraSection {
/**플루트, 클라리넷, 오보 같은 목관악기. */
WOODWIND,
/** 프롄치 호른, 트럽멧 같은 금관악기. */
BRASS,
/** 탐파니, 심벌즈 같은 타악기. */
PERCUSSION,
/** 바이올린, 첼로 같은 현악기. */
STRING ;
}
Java
복사
•
애너테이션 타입을 문서화 할 때는 멤버들에도 모두 주석을 달아야 한다.
/**
* 이 애너테이션이 달린 메서드는 명시한 예외를 던져야만 성공하는
* 테스트 메서드임을 나타낸다.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
/**
* 이 애너데이션을 단 테스트 메서드가 성공하려면 던져야 하는 예외.
* (이 클래스의 하위 타입 예외는 모두 허용된다.)
*/
Class<? extends Throwable> value();
}
Java
복사
•
스레드가 안전하든 안전하지 않든 API 설명에는 반드시 스레드 안전 수준을 포함해야 한다.