44. 모든 API 요소에 문서화 주석을 달라.

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

/**
 * Returns the element at the specified position in this list.
 *
 * <p>This method is <i>not</i> guaranteed to run in constant
 * time. In some implementations it may run in time proportional
 * to the element position.
 *
 * @param index index of the element to return; must be
 *        non-negative and less than the size of this list
 * @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);

• 제네릭 자료형이나 메서드에 주석을 달 때는 모든 자료형 인자들을 설명해야한다. ```java /**
• An object that maps keys to values (중략) *
• @param the type of keys maintained by this maps

• @param the type of mapped values */ public interface Map<K, V> { .... } ```

• enum자료형에 주석을 달 때는 자료형이나 public메서드 뿐 아니라, 상수 각각에도 주석을 달아 주어야 한다. ```java /**

• 교향악단에서 쓰이는 악기 종류 */ public enum OrchestraSection{ /** 플루트, 클라리넷, 오보와 같은 목관악기 */ WOODWIND,

  /** 프렌치 혼이나 트럼펫 같은 금관 악기 */ BRASS,

  /** 팀파니나 심벌즈 같은 타악기 */ PERCUSSION,

  /** 바이올린이나 첼로 같은 현악기 */ STRING; } ```

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

자바 1.5부터는 패키지 수준 문서화 주석(package-level doc comment)은 package.html대신 package-info.java에 두어야 한다.

javadoc tag를 달자.

• @param 인자
• @return 반환값을 설명
• @throws 어떤 조건(if)에 예외가 발생하는지 설명
• {@code} 코드 서체로 표기, HTML 마크업 무력화
• {@literal} {@code}와 비슷하나 코드 서체로 표기되지 않음

주석을 달 때 명심해야 일번적 원칙은, 문서화 주석은 소스 코드로 보나 javadoc으로 변환한 결과물로 보나 읽을 만해야 한다.

참고 : How to Write Doc Comments for the Javadoc Tool