공개된 API요소에는 항상 문서화 주석을 작성하라 - [8장. 메서드(아이템56)]

📙 1. 문서화 주석 작성 방법

  자바에는 소스코드 파일에서 문서화 주석(doc comment; 자바독 주석)이라는 특수한 형태로 기술된 설명을 추려 API 문서로 변환하여 보여주는 자바독이 있다.

  문서화 주석을 작성하는 규칙은 '문서화 주석 작성법(How to Write Doc Comments)'에 기술되어 있다. 해당 문서에 더해서 추가적으로 알아야 하는 내용은 아래와 같다.

• API를 올바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다.
• 직렬화할 수 있는 클래스라면 직렬화 형태에 관해서도 적어야 한다.
• 기본 생성자에는 문서화 주석을 달 방법이 없으니 공개 클래스는 절대 기본 생성자를 사용하면 안 된다.
• 유지보수까지 고려한다면 대다수의 공개되지 않은 클래스, 인터페이스, 생성자, 메서드, 필드에도 문서화 주석을 달아야 한다.
• 메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다.
• 상속용으로 설계된 클래스의 메서드가 아니라면 그 메서드가 어떻게 동작하는지가 아니라 무엇을 하는지를 기술해야 한다.
• 문서화 주석에는 클라이언트가 해당 메서드를 호출하기 위한 전제조건(precondition)을 모두 나열해야 한다.
• 또한 메서드가 성공적으로 수행된 후에 만족해야 하는 사후조건(postcondition)도 모두 나열해야 한다.
• 전제조건과 사후조건뿐만 아니라 부작용도 문서화해야 한다.
• 메서드의 계약(contract)을 완벽히 기술하려면 모든 매개변수에 @param 태그를, 반환 타입이 void가 아니라면 @return 태그를, 발생할 가능성이 있는 모든 예외에 @throws 태그를 달아야 한다.
• 클래스를 상속용으로 설계할 때는 자기 사용 패턴(self-use pattern)에 대해서도 문서에 남겨 다른 프로그래머에게 그 메서드를 올바로 재정의하는 방법을 알려줘야 한다. (@implSpec 활용)
• 각 문서화 주석의 첫 번째 문장은 해당 요소의 요약 설명(summary description)으로 간주된다.
• 요약 설명은 반드시 대상의 기능을 고유하게 기술해야 한다.
• 클래스, 인터페이스, 필드의 요약 설명은 대상을 설명하는 명사절이어야 한다.
• 제네릭 타입이나 제네릭 메서드를 문서화할 때는 모든 타입 매개변수에 주석을 달아야 한다.
• 열거타입을 문서화할 때는 상수들에도 주석을 달아야 한다.
• 에너테이션 타입을 문서화할 때는 멤버들에도 모두 주석을 달아야 한다.
• 패키지를 설명하는 문서화 주석은 package-info.java 파일에 작성한다.
• 모듈 시스템을 사용한다면 모듈 관련 설명은 module-info.java 파일에 작성한다.
• 클래스 혹은 정적 메서드가 스레드 안전하든 그렇지 않든, 스레드 안전 수준을 반드시 API 설명에 포함해야 한다.
• 복잡한 API라면 문서화 주석 외에도 전체 아키텍처를 설명하는 링크를 제공하면 좋다.

 

📙 2. 문서화 주석 작성 시 도움이 되는 태그 목록

📌 1. HTML 태그 사용

/**
 * ...
 * <p>This method is <i>not</i> guarenteed to run in constant</p>
 * ...
 */

  자바독 유틸리티는 문서화 주석을 HTML로 변환하므로 문서화 주석 안의 HTML 요소들이 최종적으로 HTML 문서에 반영된다.

📌 2. {@code}

/**
 * ...
 * @throws IndexOutOfBoundsException if the index is out of range
 *          ({@code index < 0 || index >= this.size()})
 * ...
 */

  태그로 감싼 내용에 포함된 HTML 요소나 다른 자바독 태그를 무시한다. 그렇기 때문에 HTML 메타문자인 < 기호 등을 별다른 처리 없이 바로 사용할 수 있는 것이다.

  여러 줄로 된 코드를 예시로 넣고 싶으면 아래와 같이 <pre> 태그를 이용하면 된다.

/**
 * ...
 * @throws IndexOutOfBoundsException if the index is out of range
 *          (<pre>{@code ... 코드 ... }</pre>)
 * ...
 */

📌 3. {@literal}

/**
 * ...
 * {@literal {r} < 1} 이면 기하 수열이 수렴한다.
 * ...
 */

  {@literal}을 이용하여 HTML 메타문자를 포함시킬 수 있다. 이것 또한 {@code}처럼 HTML 마크업이나 자바독 태그를 무시하게 해 준다. {@code}와의 차이점은 코드 폰트로 렌더링을 하지 않는다는 것이다.

  그리고 이를 이용하여 의도치 않은 마침표를 포함한 텍스트를 작성할 수 있다.

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

📌 4. {@index}

/**
 * ...
 * This method complies with the {@index IEEE 754} standard.
 * ...
 */

  자바 9부터는 자바독이 생성한 HTML 문서에 검색(색인) 기능이 추가되었다. {@index} 태그를 사용해 API에서 중요한 용어를 추가로 색인화 할 수 있다.

📌 5. {@inheritDoc}

  {@inhericDoc} 태그를 사용해 상위 타입의 문서화 주석 일부를 상속할 수 있다. 이는 자신이 구현한 인터페이스의 문서화 주석을 복사해 붙여 넣지 않고 재사용할 수 있다는 뜻이다.

 

 

해당 글은 Joshua Bloch 님의 'Effective Java 3/E'를 참고하였습니다.