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} 태그의 효과는 두 가지다
1. 태그로 감싼 내용을 코드용 폰트로 렌더링한다.
2. 태그로 감싼 내용에 포함된 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}
*/

@literal를 처리하지않으면 Mrs. 까지 요약 설명이 된다.
자바10 부터는 {@summary}라는 요약 설명 전용 태그가 추가되었다.
```
/**
* {@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 태그를 찾아줌
🍑 결론

peaches-book-study / effective-java

Item 56. 공개된 API 요소에는 항상 문서화 주석을 작성하라 #55