Item56. 공개된 API 요소에는 항상 문서화 주석을 작성하라!
Intro
- API를 쓸모 있게 하려면 잘 작성된 문서도 곁들여야 한다.
- 자바에서는 자바독(Javadoc)이라는 유틸리티가 API 문서 작성을 돕는다.
- 자바독은 소스코드 파일에서 문서화 주석이라는 특수한 형태로 기술된 설명을 추려 API 문서로 변환해준다.
문서화 주석 작성 규칙
- 공식 언어 명세에 속하진 않지만 자바 프로그래머라면 응당 알아야 하는 업계 표준 API다.
- ‘문서화 주석 작성법’ 웹페이지에 규칙이 기술되어 있다.
- 자바 버전이 올라가며 추가된 중요한 자바독 태그로는
@literal,@code,@implSpec,@index를 꼽을 수 있다.
자바독 작성의 유의 사항
- API를 올바르게 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달자.
- 직렬화 가능 클래스라면 직렬화 형태에 관해서도 적어야 한다.
- 문서화 주석이 없다면 자바독도 그저 공개 API 요소들의 ‘선언’만 나열해주는 게 전부다.
- 기본 생성자에는 문서화 주석을 달 수 없다. 그러니 공개 클래스는 절대 기본 생성자를 사용하면 안 된다.
- 유지보수까지 고려해 공개되지 않은 클래스, 인터페이스, 생성자, 메서드, 필드에도 문서화 주석을 달아야 할 것이다.
- 메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술하자.
- 상속용으로 설계된 클래스의 메서드가 아니라면 무엇을 하는지 기술해야 한다.
- how가 아닌 what을 기술해야 한다.(어떻게 동작하는 지가 아닌 무엇을 하는지에 초점을 두자)
- 해당 메서드 호출 시 클라이언트가 해둬야 하는
전제조건을 모두 나열해야 한다. - 메서드가 성공적으로 수행한 후 만족해야 하는
사후조건도 모두 나열해야 한다. @throws태그로 비검사 예외를 선언해 전제조건을 암시적으로 기술한다. 비검사 예외 하나는 전제조건 하나와 연결된다.@param태그로 그 조건에 영향을 받는 매개변수에 기술할 수도 있다.부작용도 문서화해야 한다. 부작용이란 사후조건으로 명확히 나타나진 않지만 시스템 상태변화를 가져오는 것을 뜻한다.(ex. 백그라운드 스레드 실행시키는 메서드임을 밝히기)
- 자바독 유틸리티는 문서화 주석을 HTML로 변환하므로 문서화 주석 안의 HTML 요소들이 최종 HTML 문서에 반영된다.
- 명문 문서화 주석에서 쓰인 “this”는 관례상 호출된 메서드가 자리하는 객체를 가리킨다.
- 여러 클래스가 상호작용하는 복잡한 API라면 문서화 주석 외에도 전체 아키텍처를 설명하는 별도 설명이 필요하다. 이런 설명 문서가 있다면 문서화 주석에서 링크를 제공해주면 좋다.
자바독 태그
@param
- 모든 매개변수에 달아야 한다.
- 해당 매개변수가 뜻하는 값을 설명하는 명사구
@return
- 반환 타입이 void가 아니라면 달아야 한다.
- 반환값을 설명하는 명사구
@throws
- 발생할 가능성이 있는 (검사든 비검사든) 모든 예외에 달아야 한다.
- 태그의 설명은 if로 시작해 해당 예외를 던지는 조건을 설명하는 절이 뒤따른다.
{@code}
- 태그로 감싼 내용을 코드용 폰트로 렌더링한다.
- 태그로 감싼 내용에 포함된 HTML 요소나 다른 자바독 태그를 무시한다.
- 문서화 주석에 여러 줄로 된 코드 예시를 넣으려면
<pre>{@code ... 코드 ...}</pre>형태로 사용하면 된다. @기호에는 무조건 탈출문자를 붙여야 한다. 문서화 주석 안의 코드에서 애너테이션을 사용한다면 주의하자.
@implSpec
- 클래스 상속용으로 설계할 때는 자기사용(self-use) 패턴에 대해서도 문서로 남겨야 다른 프로그래머가 올바르게 재정의하도록 도울 수 있다.
- 자기사용 패턴은 자바 8에 추가된
@implSpec태그로 문서화한다. - 해당 메서드와 하위 클래스 사이의 계약을 설명한다. 하위 클래스들이 메서드를 상속하거나 super 키워드로 호출할 때 어떻게 동작하는지 명확히 인지하고 사용할 수 있게 돕는다.
-tag "implSpec:a:Implementation Requirements"스위치를 켜줘야@implSpec태그를 무시하지 않는다.
{@literal}
- API 설명에
<, >, & 등의 HTML 메타문자를 포함시키려면{@literal}태그를 사용하자. - 이 태그는 HTML 마크업이나 자바독 태그를 무시하게 해준다.
{@inheritDoc}
- 자바독은 메서드 주석을 ‘상속’시킬 수 있다.
- 이 태그를 사용해 상위 타입의 문서화 주석 일부를 상속할 수 있다.
- 클래스는 자신이 구현한 인터페이스의 문서화 주석을 재사용할 수 있다는 뜻이다.
- 이 기능을 사용하면 똑같은 문서화 주석 여러 개를 유지보수하는 부담이 줄어든다. 하지만 사용하기 까다롭고 제약도 있다.
관례
- 관례상
@param,@return,@throws태그의 설명에는 마침표를 붙이지 않는다.
요약 설명
- 각 문서화 주석의 첫 번째 문장은 해당 요소의 요약 설명으로 간주된다.
- 그렇다고 “요약 설명이란 문서화 주석의 첫 문장이다”라고 말하면 오해의 소지가 생긴다. 요약 설명이 완전한 문장이 되는 경우는 드물기 때문이다.
- 요약 설명은 반드시 대상의 기능을 고유하게 기술해야 한다.
- 한 클래스(혹은 인터페이스) 안에서 요약 설명이 똑같은 멤버(혹은 생성자)가 둘 이상이면 안 된다.
- 다중정의된 메서드들의 설명은 같은 문장으로 시작하는 게 자연스럽겠지만 문서화 주석에서는 허용되지 않는다.
- 요약 설명에서는 마침표에 주의해야 한다. 마침표가 나오는 부분까지만 split 되어 설명되니 말이다. {@literal} 태그로 감싸주면 해결된다.
- 마침표 뿐만 아니라, 스페이스, 탭, 줄바꿈으로 구성된 공백이나 소문자가 아닌 문자로 시작하는 다음 문장이 split의 구분자이다.
- 메서드와 생성자의 요약 설명은 해당 메서드와 생성자의 동작을 설명하는 동사구여야 한다.
- 2인칭 문장이 아닌 3인칭 문장으로 써야 한다.(한글에선 차이 없다.)
- 클래스, 인터페이스, 필드의 요약 설명은 대상을 설명하는 명사절이다. 클래스와 인터페이스의 대상은 그 인스턴스고, 필드의 대상은 필드 자신이다.
- 클래스, 인터페이스, 필드 값은 API 요소의 색인은 자동 생성된다.
{@index}태그를 사용해 API에서 중요한 용어를 추가로 색인화할 수 있다. - 문서가 잘 쓰인 것인지 확인하는 유일한 방법은 자바독 유틸리티가 생성한 웹페이지를 읽어보는 길뿐이다.
제네릭, 열거 타입, 애너테이션의 문서화 주석
제네릭 타입이나 제네릭 메서드
- 모든 타입 매개변수에 주석을 달아야 한다.
열거 타입
- 상수들에도 주석을 달아야 한다.
- 열거 타입 자체와 그 열거 타입의 public 메서드에도 주석을 달아야 한다.
애너테이션 타입
- 멤버들에도 모두 주석을 달아야 한다.
- 애너테이션 타입 자체에도 주석을 달아야 한다.
- 필드 설명은 명하구로 한다.
- 애너테이션 타입의 요약 설명은 프로그램 요소에 이 애너테이션을 단다는 것이 어떤 의미인지 설명하는 동사구다.
스레드 안전성, 직렬화 가능성
- 클래스 혹은 정적 메서드가 스레드 안전하든 그렇지 않든, 스레드 안전 수준을 반드시 API 설명에 포함해야 한다.
- 직렬화할 수 있는 클래스라면 직렬화 형태도 API 설명에 기술해야 한다.
핵심 정리
- 문서화 주석은 API를 문서화하는 가장 훌륭하고 효과적인 방법이다.
- 공개 API라면 빠짐없이 설명을 달아야 한다.
- 표준 규약을 일관되게 지키자.
- 문서화 주석에 임의의 HTML 태그를 사용할 수 있음을 기억하자.
- 단, HTML 메타문자는 특별하게 취급해야 한다.
Comments powered by Disqus.