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

API를 쓸모 있게 하려면 잘 작성된 문서도 곁들여야 한다.

자바에서는 자바독(Javadoc)이라는 유틸리티가 소스코드 파일에서 문서화 주석(doc comment; 자바독 주석)이라는 특수한 형태로 기술된 설명을 추려 API 문서로 변환해 준다.

 

문서화 주석

 

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

이 규칙은 문서화 주석 작성법 (How to Write Doc Comments) 웹 페이지에 기술되어 있다.

 

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

 

 

 

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

• 상속용으로 설계된 클래스의 메서드가 아니라면 그 메서드가 어떻게 동작하는지가 아니라 무엇을 하는지를 기술해야 한다. (how가 아닌 what)

 

 

문서화 주석에는 클라이언트가 해당 메서드를 호출하기 위한 전제조건을 모두 나열해야 한다.

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

 

 

메서드가 성공적으로 수행된 후에 만족하는 사후조건도 모두 나열해야 한다.

 

 

 

부작용도 문서화해야 한다.

• 부작용이란 사후조건으로 명확히 나타나지는 않지만 시스템의 상태에 어떠한 변화를 가져오는 것을 뜻한다.
• ex) 백그라운드 스레드를 시작시키는 메서드라면 그 사실을 문서에 밝혀야 한다.

 

 

메서드의 계약(contract)을 완벽히 기술하려면 모든 매개변수에 @param 태그를, 반환 타입이 void가 아니라면 @return 태그를, 발생할 가능성이 있는 모든 예외에 @throw 태그를 달아야 한다.

 

• 관례상 @param 태그와 @return 태그의 설명은 해당 매개변수가 뜻하는 값이나 반환값을 설명하는 명사구를 쓴다.
• 드물게 명사구 대신 산술 표현식을 쓰기도 한다.
• @param, @return, @throw 태그의 설명에는 마침표를 붙이지 않는다. (설명을 한글로 작성할 경우 온전한 종결 어미로 끝나면 마침표를 써주는 게 일관돼 보인다.)

 

 

BigInteger의 API 문서 - 영문

 

 

BigInteger의 API 문서 - 한글

 

 

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

 

 

@throws 절에 사용한 {@code} 태그의 효과

1. 태그로 감싼 내용을 코드용 폰트로 렌더링
2. 태그로 감싼 내용에 포함된 HTML 요소나 다른 자바독 태그를 무시. 이 덕분에 HTML 메타문자인 < 기호 등을 별다른 처리 없이 바로 사용할 수 있다.

 

문서화 주석에 여러 줄로 된 코드 예시를 넣으려면 <pre>{@code.. 코드...}</pre> 형태처럼 <pre> 태그로 감싸면 된다.

단, @ 기호에는 무조건 탈출문자를 붙여야 하므로 문서화 주석 안의 코드에서 애너테이션을 사용한다면 주의하자.

 

 

 

영문 문서화 주석의 'this list', 한글 문서화 주석의 '이 리스트'

• 관례상 인스턴스 메서드의 문서화 주석에 쓰인 this는 호출된 메서드가 자리하는 객체를 가리킨다.

 

 

클래스를 상속용으로 설계할 때는 자기 사용 패턴(self-use pattern)에 대해서도 문서에 남겨 다른 프로그래머에게 그 메서드를 올바로 재정의하는 방법을 알려줘야 한다.

• 자기 사용 패턴은 자바 8에 추가된 @implSpec 태그로 문서화한다.
• 일반적인 문서화 주석은 해당 메서드와 클라이언트 사이의 계약을 설명하지만, @implSpec 주석은 해당 메서드와 하위 클래스 사이의 계약을 설명한다.
• 즉, 하위 클래스들이 그 메서드를 상속하거나 super 키워드를 이용해 호출할 때 그 메서드가 어떻게 동작하는지를 명확히 인지하고 사용하도록 해줘야 한다.

 

 

 

 

API 설명에 <, >, & 등의 HTML 메타문자를 포함시키려면 특별한 처리를 해줘야 한다.

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

|r| < 1이면 기하 수열이 수렴한다.로 변환된다.

 

 

 

각 문서화 주석의 첫 번째 문장은 해당 요소의 요약 설명(summary description)으로 간주된다.

• 요약 설명은 반드시 대상의 기능을 고유하게 기술해야 한다.
• 한 클래스(인터페이스) 안에서 요약 설명이 똑같은 멤버(생성자)가 둘 이상이면 안되다.
• 다중정의된 메서드가 있다면 특히 더 조심하자.
• 다중정의된 메서드들의 설명은 같은  문장으로 시작하는 게 자연스럽겠지만 문서화 주석에서는 허용되지 않는다.

 

 

요약 설명에서는 마침표(.)에 주의해야 한다.

 

ex) "머스터드 대령이나 Mrs. 피콕 같은 용의자"

"머스터드 대령이나 Mrs" 까지만 요약 설명이 된다.

• 요약 설명이 끝나는 판단 기준은 처음 발견되는 {<마침표><공백><다음 문장 시작>} 패턴의 <마침표>까지다.
• <공백>은 스페이스, 탭, 줄 바꿈이다.
• <다음 문장 시작> 소문자가 아닌 문자

 

의도치 않은 마침표를 포함한 텍스트를 {@literal}로 감싸주자.

자바 10부터 {@summary}라는 요약 설명 전용 태그가 추가되었다.

 

 

 

 

 

메서드와 생성자의 요약 설명은 아래처럼 해당 메서드와 생성자의 동작을 설명하는 주어 없는 동사구여야 한다.

• ArrayList(int initialCapacityp) : 지정한 초기 용량을 갖는 빈 리스트를 생성한다.
• Collection.size() : 이 컬렉션 안의 원소 개수를 반환한다.

 

 

 

클래스, 인터페이스, 필드의 요약 설명은 대상을 설명하는 명사절이어야 한다.

• Instant : 타임라인상의 특정 순간
• Math.PI : 원주율에 가장 가까운 double 값

 

 

문서화 주석에서 제네릭, 열거 타입, 애너테이션은 특별히 주의해야 한다.

 

1. 제네릭 타입이나 제네릭 메서드를 문서화할 때는 모든 타입 매개변수에 주석을 달아야 한다.

 

 

 

 

2. 열거 타입을 문서화할 때는 상수들에도 주석을 달아야 한다.

 

 

 

3. 애너테이션 타입을 문서화할 때는 멤버들에도 모두 주석을 달아야 한다.

• 필드 설명은 명사구로 한다.
• 애너테이션 타입의 요약 설명은 프로그램 요소에 이 애너테이션을 단다는 것이 어떤 의미인지를 설명하는 동사구로 한다.
• 한글로 쓴다면 동사로 끝나는 평범한 문장이면 된다.

 

 

 

패키지를 설명하는 문서화 주석은 package-info.java 파일에 작성한다.

• 이 파일은 패키지 선언을 반드시 포함해야 하며 패키지 선언 관련 애너테이션을 추가로 포함할 수도 있다.
• 자바 9부터 지원하는 모듈 시스템을 사용한다면 모듈 관련 설명은 module-info.java 파일에 작성하면 된다.

 

 

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

1. 스레드 안전성
2. 직렬화 가능성

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

 

 

자바독은 메서드 주석을 상속시킬 수 있다.

• {@inheritDoc} 태그를 사용해 상위 타입의 문서화 주석 일부를 상속할 수 있다.

 

 

공개된 모든 API 요소에 문서화 주석을 달았더라도 충분하지 않을 때가 있다.

• 여러 클래스가 상호작용하는 복잡한 API라면 문서화 주석 외에도 전체 아키텍처를 설명하는 별도의 설명이 필요할 때가 있다.
• 이런 설명 문서가 있다면 관련 클래스나 패키지의 문서화 주석에서 그 문서의 링크를 제공해 주자.

 

 

자바독은 프로그래머가 자바독 문서를 올바르게 작성했는지 확인하는 기능을 제공하며, 이번 아이템에서 고개한 권장사항 중 상당수를 검사해 준다.

IDE의 체크스타일, HTML유효성 검사기 등을 통해 오류를 줄여보자.

 

 

 

결론

 

• 문서화 주석은 API를 문서화하는 가장 훌륭하고 효과적인 방법이다.
• 공개 API라면 빠짐없이 설명을 달자.
• 문서화 주석의 표준 규약을 일관되게 지키자.
• 문서화 주석에 임의의 HTML 태그를 사용할 수 있으나 HTML 메타문자는 특별하게 취급해야 한다.
• API를 설명한 문서가 잘 쓰인 지 확인하는 유일한 방법은 자바독 유틸리티가 생성한 웹페이지를 읽어보는 길 뿐이다.