<Effective Java> RULE 44 모든 API요소에 문서화 주석을 달라

 

좋은 API문서를 만들려면 API에 포함된 모든 클래스, 인터페이스, 생성자, 메서드, 그리도 필드 선언에 문서화 주석을 달아야한다.

 

· 계승을 위해 설계된 메서드가 아니라면 메서드가 무엇을 하는지를 설명해야하며 어떻게 그 일을 하는지 설명해서는 안된다.

· 해당 메서드모든 선행조건과 후행조건을 나열해야한다.

ㄴ 선행조건 : 클라이언트가 메서드를 호출하려면 반드시 참이어야 하는 조건

· 무점검 예외에 대한 @Throws, @Param태그를 통해 명시할 수 있다.

ㄴ 후행조건 : 메서드 실행이 성공적으로 끈난 다음에 만족되어야 하는 조건

· 부작용에 대해서 문서화 해야한다.

ㄴ 후면 쓰레드를 실행한다면 문서는 그 사실을 명시해야 한다.

· 클래스나 메서드의 스레드 안전성에 대해 문서화해야한다.

/**
 * 
 * <p>This method is <i>not</i> guaranteed to run in constant time.
 * 
 * @author    ismyeong
 * @writeday  2018. 3. 20.
 * @param index index of element to return; must be non-negative and less than the size of this list     
 * @throws IndexOutOfBoundsException
 *         ({@code index < 0 || index >= this.size()})
 * @return the element at the specified position in this list
 *
 */
<E> E get(int index) {
    return null;
}

 

· 주석에 HTML태그가 사용되었다.

ㄴ Javadoc유틸리티는 문서화 주석을 HTML문서로 변환한다. 따라서 주석에 포함된 HTML요소는 해당 문서에 포함된다.

· {@code} 태그가 사용되었다.

ㄴ 해당 코드가 코드 서체로 표시되도록 하는것

ㄴ 그 안에 포함된 모든 HTML 마크업이나 Javadoc 태그가 위력을 발휘하지 못하도록 하는 것

ㄴ 이스케이프 처리

· <, >, & 와 같은 메타문자들은 {@literal} 태그를 사용한다.

The triangle inequality is {@literal |x + y| < |x| + |y|}.

 

· 메서드나 생성자의 요약문은 무슨일을 하는지 기술하는 완전한 동사구로 작성.

//Constructs an empty list with the specified initial capacity.
ArrayList(int initialCapacity){}

 

· 클래스와 인터페이스의 요약문은 만들어진 객체가 무엇을 나타내는지 명사구로 작성.

//A task that can be scheduled for one-time or repeated execution by a Timer.
int TimerTask;

 

· 제네릭 자료형, 메서드에 주석은 모든 자료형 인자를 설명해야한다.

/**
 *
 * an object that maps keys to values. A map cannot contain duplicate keys;
 *
 * @param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
 * 
 */
public interface Map<K, V>{
}

 

· Enum 자료형 : 자료형이나 public 메서드 뿐만 아니라 상수 각각에도 주석을 달아주어야 한다.

/**
 * 교향악단에서 쓰이는 악기 종류
 */
public enum OrchestraSection{
    /** 플루트, 클라리넷, 오보에 같은 목관악기 */
    WOODWIND,
    
    /** 프랜치 혼이나 트럼펫 같은 금관악기 */
    BRASS,
    
    /** 팀파니나 심벌즈 같은 타악기 */
    PRECUSSION,
    
    /** 바이올린이나 첼로 같은 현악기 */
    STRING;
}

 

· 어노테이션 자료형 : 자료형 뿐만 아니라 모든 멤버에도 주석을 달아야 한다.

/**
 * 
 * 지정된 예외를 반드시 발생시켜야 하는 테스트 메서드임을 명시
 *
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest{
    /**
     * 
     * 어노테이션이 붙은 테스트 메서드가 테스트를 통과하기 위해
     * 반드시 발생시켜야 하는 예외. (이 Class 객체가 나타내는 자료형의 하위 자료형이기만
     * 하면 어떤 예외는 상관 없다.)
     * 
     */
    Class<? extends Throwable> value();
}

 

· 릴리즈 1.5부터는 패키지 수준 문서와 주석 package-info.java에 두어야 한다.

· 문서화 주석을 제대로 만들기 위해서는 Oracle의 How to Write Doc Comments[javadoc-guide]를 꼭 읽자

 

결론

· 문서화 주석은 API문서를 만드는 가장 효과적인 방법이다.

· 공개 API 요소라면 필수적으로 겸비해야 하느 부분이다.