[Effective Java] 아이템56 공개된 API 요소에는 항상 문서화 주석을 작성하라

■ 자바독(Javadoc)이란?

 

• API 문서화 유틸리티
• 소스코드 파일에서 문서화 주석이라는 특수한 형태로 기술된 설명을 추려 API 문서로 변환해줌

 

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

여러분의 API를 올바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다.

 

• 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에doc comment를 달아야 한다.
• 공개 클래스는 기본 생성자에 주석을 달 수 있는 방법이 없으니 절대 기본 생성자를 사용해서는 안된다.

 

■ 메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술

 

• how가 아닌 what을 기술할 것. (상속용으로 설계된 API가 아닌 이상)
• 메서드를 성공적으로 호출하기 위한 전제조건을 나열할 것
• 메서드가 성공적으로 수행된 후에 만족해야 하는 사후조건을 나열할 것
• 부작용(사후조건으로 명확하게 나타나지는 않지만 시스템의 상태에 어떠한 변화를 가져오는 것)도 문서화할 것 (ex. 백그라운드 스레드를 시작하는 메서드)

 

■ javadoc 주석 태그

 

@param 

• 매개 변수 설명
• 모든 매개변수에 설명을 달아야한다.

 

@return

• 반환 값 설명
• 반환 타입이 void가 아니면 달아야한다.

 

@throws

• if로 시작해 해당 예외를 던지는 조건 설명

{@code}

• 주석 내에 HTML 요소나 다른 자바독 태그를 무시한다.
• 주석에 여러 줄로 된 코드 예시를 넣으려면 {@code}를 <pre>태그로 감싸준다. <pre>{@code ...코드... }</pre>
  

 

{@literal}

• 주석 내에 HTML 요소나 다른 자바독 태그를 무시한다.
• {@code}와 비슷하지만 코드 폰트로 렌더링하지 않는다.

@implSpec

• 해당 메서드와 하위 클래스 사이의 계약을 설명
• 하위 클래스들이 그 메서드를 상속하거나 super 키워드를 이용해 호출할 때 그 메서드가 어떻게 동작하는지 명확히 인지할 수 있도록 도와준다.

{@inheritDoc}

• 상위 타입의 문서화 주석 일부를 상속할 수 있다.

 

■ API 문서화에서 자주 누락되는 설명 두가지 

 

• 클래스 혹은 정적 메서드가 스레드 안전하든 그렇지 않든, 쓰레드 안전 수준을 반드시 API 설명에 포함해야 한다.
• 직렬화할 수 있는 클래스라면 직렬화 형태도 API 설명에 기술해야 한다.

 

■ 핵심 정리

 

• 문서화 주석은 aPI를 문서화하는 가장 훌륭하고 효과적인 방법이다.
• 공개 API라면 빠짐없이 설명을 달아야 한다.
• 표준 규약을 일관되게 지키자.
• 문서화 주석에 임의의 HTML 태그를 사용할 수 있음을 기억하라. 단, HTML 메타문자는 특별하게 취급해야 한다.

 

 

REFERENCE

• https://hirlawldo.tistory.com/104

[Effective Java] item 56. 공개된 API 요소에는 항상 문서화 주석을 사용하라