[이펙티브 자바] Item56 - 공개된 API 요소에는 항상 문서화 주석을 작성하라

API를 쓸모 있게 하려면 잘 작성된 문서도 함께 제공해야 한다. 자바에서는 자바독이라는 유틸리티가 이 작업을 도와준다.

문서화 주석을 작성하는 규칙은 공식 언어 명세에 속하진 않지만 자바 프로그래머라면 응당 알아야 하는 업계 표준 API라 할 수 있다.

 

API를 올바르게 문서화하는 방법

• API를 올바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다.
• 직렬화할 수 있는 클래스라면 직렬화 형태에 대해서도 적어야 한다,
• 문서가 잘 갖춰지지 않은 API는 쓰기 헷갈려서 오류의 원인이 되기 쉽다. 꼭 문서화를 하자.
• 기본 생성자에는 문서화 주석을 달 수 없으니 공개 클래스는 절대 기본 생성자를 사용하지 말자.
• 유지보수를 고려한다면 대다수의 공개되지 않은 클래스, 인터페이스, 생성자, 메서드, 필드에 공개 API만큼은 아니더라도 문서화 주석을 달자.

 

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

• 상속용으로 설계 된 클래스의 메서드가 아니라면 무엇을 하는지를 기술해야 한다. 즉, how가 아닌 what을 기술해야 한다.
• 해당 메서드 호출 전제조건을 모두 나열해야 한다.
• 메서드가 성공적으로 수행된 후 만족해야 하는 사후조건을 모두 나열해야 한다.
• 사후조건으로 명확히 나타나지는 않지만 시스템의 상태에 어떠한 변화를 가져오는 부작용도 문서화해야 한다.
  • ex. 백그라운드 스레드를 시작시키는 메서드면 문서에 밝혀야 한다.

 

전제조건?

일반적인 전제조건은 @throws 태그로 나타낸다.

비검사 예외를 선언하여 암시적으로 기술하며 비검사 예외 하나가 전제조건 하나와 연결된다. 또한, @param 태그를 이용해 그 조건에 영향을 받는 매개변수에 기술할 수도 있다.

 

메서드 계약(contract)

• 메서드 계약을 완벽히 기술하려면 모든 매개변수에 @param 태그를 달자.
• 반환 타입이 void가 아니라면 @return 태그를 달자.
• 발생할 가능성이 있는 모든 예외에 @throws 태그를 달자.
• @return 태그의 설명이 메서드 설명과 같다면 생략하자.

 

태그 컨벤션

• 관례상 @param 태그와 @return 태그의 설명은 해당 매개변수가 뜻하는 값이나 반환값을 설명하는 명사구를 쓴다. 드물게 산술 표현식을 사용하기도 한다.
• @param, @return, @throws 태그 설명에는 마침표를 붙이지 않는다.

다음은 이 컨벤션을 잘 지킨 문서화 주석의 예다.

List의 get() 메서드

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

 

클래스를 상속용으로 설계할 때 문서화 주석

• 자기사용 패턴에 대해서 문서에 남겨 다른 프로그래머에게 그 메서드를 올바로 재정의하는 방법을 알려주자.
• 자기사용 패턴은 @implSpec 태그로 문서화할 수 있다.
• @implSpec 주석은 해당 메서드와 하위 클래스 사이의 계약을 설명해야 한다.
• 하위 클래스들이 메서드를 상속하거나 super 키워드로 호출할 때 어떻게 동작하는지 명확하게 인지할 수 있도록 문서를 작성하자.

 

API 설명에 HTML 메타 문자 포함시키기

• {@literal} 태그로 감싸면 HTML 마크업이나 자바독 태그를 무시하게 해 준다.
• {@code} 태그와 비슷하지만 코드 폰트로 렌더링 하지 않는다.

// 예시

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

-> |r| < 1이면 기하 수열이 수렴한다.

 

그 외 태그들

• {@summary} 태그를 이용해 요약 설명을 깔끔하게 처리할 수 있다.
• {@index} 태그를 사용해 API 중요한 용어를 색인화할 수 있다.
• {@inheritDoc} 태그는 상위 타입의 무선화 주석 일부를 상속할 수 있게 해 준다.

 

제네릭, 열거 타입, 애너테이션 문서화 주석

• 제네릭 타입이나 제네릭 메서드를 문서화할 때는 모든 타입 매개변수에 주석을 달아야 한다.
• 열거 타입을 문서화할 때도 마찬가지로 상수들에 주석을 달아야 한다.
• 애너테이션 타입을 문서화할 때는 멤버들에도 모두 주석을 달아야 한다.

 

API 문서화에서 자주 누락되는 설명

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

 

핵심 정리

• 문서화 주석은 API를 문서화하는 가장 효과적인 방법이므로 공개 API라면 빠짐없이 설명을 달아야 한다.
• 문서화 주석에 임의의 HTML 태그를 사용할 수 있다. 단, HTML 메타 문자는 특별하게 취급해야 한다.