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

EFFECTIVE JAVA(이펙티브 자바)

 

이 포스팅에서 작성하는 내용은 EFFECTIVE JAVA(이펙티브자바) 에서 발췌하였습니다.

---

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

좋은 API를 개발하기 위해서는 해당 API에 대한 문서도 잘 작성되어야 한다.

기본적으로 API 문서는 사람이 직접 작성하므로 코드가 변경되면 매번 같이 수정해줘야 하는데, 자바에서는 Javadoc이라는 유틸리티가 이 작업을 도와준다.

 

Javadoc

• Javadoc은 프로그래머가 자바독 문서를 올바르게 작성했는 지 확인하는 기능을 제공한다.
• 자바 7에서는 명렬줄에서 -Xdoclint 스위치를 켜주면 이 기능이 활성화되고, 자바 8부터는 기본으로 작동한다.
• 소스코드 파일에서 문서화 주석이라는 특수한 형태로 기술된 설명을 추려 API 문서로 변환해준다.
• API를 올바르게 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다.
• 직렬화할 수 있는 클래스라면 직렬화 형태에 관해서도 적어야 한다.
• 메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다.
  • 상속용으로 설계된 클래스의 메서드가 아니라면 무엇을 하는지를 기술해야 한다. (즉, how가 아닌 what을 기술해야 한다.)
  • 문서화 주석에는 클라이언트가 해당 메서드를 호출하기 위한 전제조건을 모두 나열해야한다.
  • 또한 메서드가 성공적으로 수행된 후에 만족해야 하는 사후조건도 모두 나열해야 한다.
  • 일반적으로 전제조건은 @throws 태그로 비검사 예외를 선언하여 암시적으로 기술한다. 비검사 예외 하나가 전제조건 하나와 연결되는 것이다.
  • @param 태그를 이용해 그 조건에 영향받는 매개변수에 기술할수도 있다.
• 전제조건과 사후조건 뿐만 아니라 부작용도 문서화해야 한다.
• 부작용이란, 사후조건으로 명확히 나타나지는 않지만 시스템의 상태에 어떠한 변화를 가져오는 것을 뜻한다.
• 문서화 주석에 HTML 태그를 쓰기도 한다. Javadoc 유틸리티는 문서화 주석을 HTML로 변환하기 때문이다.
• 관례상, 인스턴스 메서드의 문서화 주석에 쓰인 “this”는 호출된 메서드가 자리하는 객체를 가리킨다.

 

Javadoc 주석 태그

	설명
@param	매개 변수를 설명 모든 매개변수에 설명을 달아야 함 설명에 마침표를 붙이지 않는다.
@return	반환 타입이 void가 아니라면 무엇을 return 하는 지 기술 설명에 마침표를 붙이지 않는다.
@throws	발생할 가능성이 있는 검사든 비검사든 모든 예외를 기술 설명에 마침표를 붙이지 않는다.
{@code}	주석 내에 HTML 요소나 다른 Javadoc 태그를 무시함 주석에 여러 줄로 된 코드 예시를 넣으려면 {@code …코드들…}
{@literal}	HTML 마크업이나 Javadoc 태그를 무시하게 해준다. 위의 {@code} 태그와 비슷하지만 코드 폰트로 렌더링하지 않는다.
@implSpec	해당 메서드와 하위 클래스 사이의 계약을 설명하여, 하위 클래스들이 그 메서드를 상속하거나 super 키워드를 이용해 호출할 때 그 메서드가 어떻게 동작하는지를 알려준다. 자바 11까지도 Javadoc 명령줄에서 -tag “implSpec:a:Implemtation Require ments:” 스위치를 켜주지 않으면 @imple 태그를 무시해버린다.
{@index}	클래스, 메서드, 필드 같은 API 요소의 색인은 자동으로 만들어지며, 원한다면 {@index} 태그를 사용해 API에서 중요한 용어를 추가로 색인화할 수 있다.
{@inheritDoc}	상위 타입의 문서화 주석 일부를 상속할 수 있다. 즉, 클래스는 자신이 구현한 인터페이스의 문서화 주석을 재사용할 수 있다는 것

 

 

주석 요령

• 제네릭 타입이나 제네릭 메서드를 문서화할 때는 모든 타입 매개변수에 주석을 달아야 ㅇ한다.
• 열거 타입을 문서화할 때에 상수들에도 주석을 달야아 한다.
• 애너테이션 타입을 문서화할 때는 멤버들에도 모두 주석을 달아야 한다.
• 패키지를 설명하는 문서화 주석은 package-info.java 파일에 작성한다.
• 클래스 혹은 정적 메서드가 스레드 안전하든 그렇지 않든 스레드 안전 수준을 API 설명에 포함해야 한다.