Item 56. 공개된 API 요소에는 항상 문서화 주석을 작성하라 #55
Description
Chapter : 8. 메서드
Item : 56. 공개된 API 요소에는 항상 문서화 주석을 작성하라
Assignee : byunghyunkim0
🍑 서론
API를 쓸모 있게 하려면 잘 작성된 문서도 곁들어야 한다.
- API 문서는 사람이 작성하므로 코드가 변경되면 매번 함께 수정해줘야 하는데, javadoc이라는 유틸리티가 작업을 도와준다.
javadoc
- JAVA 소스코드에서 API 문서를 html 태그형식으로 작성하게 해주는 도구이다.
/** 내용 */으로 이루어진 주석
🍑 본론
문서화 주석
API를 올바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다.
직렬화할 수 있는 클래스라면 직력화 형태에 관해서도 적어야 한다. (아이템 87)
- 문서가 잘 갖춰지지 않은 API는 쓰기 헷갈려서 오류의 원인이 되기 쉽다.
- 기본 생성자에는 문서화 주석을 달 방법이 없으니 공개 클래스는 기본 생성자를 사용하면 안된다.
- 유지보수까지 고려한다면 공개되지 않은 클래스, 인터페이스, 생성자, 메서드, 필드에도 문서화 주석을 다는것이 좋다.
메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명로하게 기술해야 한다.
-
메서드가 어떻게 동작하는지가 아니라 무엇을 하는지를 기술해야 한다.(how가 아닌 what을 기술)
-
클라이언트가 해당 메서드를 호출하기 위한 전제조건과 성공적으로 수행된 후에 만족해야 하는 사후조건도 모두 나열해야 한다.
-
전제조건은
@throws태그로 비검사 예외를 선언하여 암시적으로 기술 -
@param태그를 이용해 매개변수에 대한 내용을 기술할수 있다. -
전제 사후조건뿐만 아니라 부작용도 문서화해야 한다.
- 부작용이란 사후조건으로 명확히 나타나지는 않지만 시스템의 상태에 어떠한 변화를 가져온는 것을 뜻함
- 백그라운드 스레드를 시작시키는 메서드라면 그 사실을 문서에 밝혀야 한다.
-
메서드의 규약을 완벽히 기술하려면 태그를 활용해라
@param: 매개변수@return: 반환 타입이 void가 아니라면@throws: 발생할 가능성이 있는 모든 예외@param,@return,@throws태그의 설명에는 마침표를 붙이지 않는다.
-
문서화 주석의 예시
/**
* 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 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 >= this.size()})
*/
E get(int index) {
return null;
}{@code}
- {@code} 태그의 효과는 두 가지다
- 태그로 감싼 내용을 코드용 폰트로 렌더링한다.
- 태그로 감싼 내용에 포함된 HTML 요소나 다른 자바독 태그를 무시한다.
- HTML 메타문자인 < 기호 등을 별다른 처리 없이 사용가능
- 주석에 여러 줄로 된 코드 예시를 넣으려면
<pre>{@code ... 코드 ... }</pre>형태로 쓰면 된다.
@implSpec
- 클래스를 상속용으로 설계할 때는 자기사용 패턴에 대해서도 문서에 남겨 메서드르르 올바로 재정의하는 방법을 알려줘야 한다.
- 일반적인 문서화 주석은 해당 메서드와 클라이언트 사이의 계약을 설명한다. @implSpec 주석은 해당 메서드와 하위 클래스 사이의 계약을 설명하여 하위 클래스들이 그 메서드를 상속하거나 super 키워드를 호출할때 어떻게 동작하는지 알려준다.
- 자기사용 패턴 등 내부 구현 방식을 명확히 드러내기 위해 @implSpec 사용
/**
* Returns true if this collection is empty.
*
* @implSpec This implementation returns {@code this.size() == 0}.
*
* @return true if this collection is empty
*/
public boolean isEmpty() {
return false;
}{@literal}
HTML 마크업이나 자바독 태그를 무시하게 해준다.
API 설명에 <, >, & 등의 HTML 메타문자를 포함시키기 위한 가장 좋은 방법이 이 태그를 사용하는 것이다
@literal 태그 예시
/**
* A geometric series converges if {@literal |r| < 1}.
*/- < 기호에만 {@literal}로 감싸도 똑같지만, 코드에서의 가독성이 떨어지므로 그렇게 하지말자.
요약 설명 {@summary}
각 문서화 주석의 첫 번째 문장은 해당 요소의 요약 설명으로 간주한다.
- 요약 설명은 반드시 대상의 기능을 고유하게 기술해야 한다.
- 한 클래스 안에서 요약 설명이 똑같은 멤버가 둘 이상이면 안 된다.
- 요약 설명에서는 마침표(.)에 주의해야 한다.
/**
* A suspect, such as Colonel Mustard or {@literal Mrs. Peacock}
*//**
* {@summary A suspect, such as Colonel Mustard or Mrs. Peacock.}
*/- 메서드와 생성자의 요약 설명은 동작을 설명하는 주어가 없는 동사구여야 하며, 3인칭 문장으로 써야 한다.
- ArrayList(int initialCapcity) : Construct an empty list with the specified initial capacity.
- Collection.size() : Returns the number of elements in this collection.
- 클래스, 인터페이스, 필드의 요약 설명은 대상을 설명하는 명사절이어야 한다.
- 클래스와 인터페이스의대상은 그 인스턴스이고, 필드의 대상은 필드 자신이다.
- Instant : An instantaneous point on the time-line.
- Math.PI : The double value that is closer than any other to pi, the ratio of the circumference of a circle to its diameter.
{@index}
- 자바 9부터는 자바독이 생성한 HTML 문서에 검색(색인) 기능이 추가되었다.
- 클래스, 메서드, 필드 같은 API 요소의 색인은 자동으로 만들어지며, 원한다면 {@index} 태그를 사용해 API에서 중요한 용어를 추가로 색인화할 수 있다.
/**
* This method complies with the {@index IEEE 754} standard.
*/제네릭 타입, 제네릭 메서드
- 제네릭 타입이나 제네릭 메서드를 문서화할 때는 모든 타입 매개변수에 주석을 달아야 한다.
/**
* An object that maps keys to values. A map cannot contain
* duplicate keys; each key can map to at most one value.
*
* (Remainder omitted)
*
* @param <K> the type of keys maintained by this map
* @param <V> the type of mapped values
*/
public interface Map<k, V> { ... }열거 타입
- 열거 타입을 문서화할 때는 상수들에도 주석을 달아야 한다.
/**
* An instrument secction of a symphony orchestra.
*/
public enum OrchestraSection {
/** Woodwinds, such as flute, clarinet, and oboe. */
WOODWIND,
/** Brass instruments, such as french horn and trumpet. */
BRASS,
/** Percussion instruments, such as timpani and cymbals */
PERCUSSION,
/** Stringed instruments, such as violin and cello. */
STRING;
}애너테이션 타입
- 애너테이션 타입을 문서화할 때는 멤버들에도 모두 주석을 달아야 한다.
- 필드 설명은 명사구로 하고, 애너테이션 타입의 요약 설명은 프로그램 요소에 이 애너테이션을 단다는 것이 어떤 의미인지를 설명하는 동사구로 한다.
/**
* Indicates that the annotated method is a test method that
* must throw the designated exception to pass.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
/**
* The exception that the annotated test method must throw
* in order to pass. (The test is permitted to throw any
* subtype of the type described by this class object.)
*/
Class<? extends Throwable> value();
}패키지
- 패키지를 설명하는 문서화 주석은 package-info.java 파일에 작성한다.
- 자바 9부터 지원하는 모듈 시스템도 모듈 관련 설명은 module-info.java 파일에 작성하면 된다.
스레드 안전성 & 직렬화 가능성
- API 문서화에서 자주 누락되는 설명이 두 가지 있으니, 바로 스레드 안정성과 직렬화 가능성이다.
- 클래스 혹은 메서드가 스레드 안전하든 그렇지 않든, 스레드 안전 수준을 반드시 API 설명에 포함해야 한다.
메서드 주석 상속 & {@inheritdoc}
- 문서화 주석이 없는 API 요소를 발견하면 자바독이 가장 가까운 문서화 주석을 찾는다.
{@inheritDoc}태그를 사용하여 상위 타입의 문서화 주석 일부를 상속시킬 수 있다.- 사용하기 까다롭고 제약도 조금 있다.
자바독 문서 기능
- 자바독은 프로그래머가 자바독 문서르르 올바르게 작성했는지 확인하는 기능을 제공한다. (자바 8부터 기본으로 작동)
- 체크스타일 같은 IDE 플러그인을 사용하면 더 완벽하게 검사됨.
- HTML 파일을 HTML 유효성 검사기로 돌리면 오류를 한층 더 줄일 수 있다. 잘못 사용한 HTML 태그를 찾아줌