[Effective Java] 외부에 제공하는 모든 API 요소에 대해 문서화 주석을 넣자.

[Effective Java] 외부에 제공하는 모든 API 요소에 대해 문서화 주석을 넣자.

-
사용 가능한 API 라면 반드시 문서화해야 한다.
만일 문서화 주석 규칙에 친숙하지 않다면 배워야 한다.


-
API 를 문서화하려면, 외부에 제공하는 모든 클래스, 인터페이스, 생성자, 메소드, 필드의 선언부 앞에 문서화 주석을 넣어야 한다.
만일 어떤 클래스가 직렬화될 수 있다면 직렬화 형태도 문서화해야 한다.


-
문서화 주석이 빠진 API 를 사용하는 것은 실망스럽고 에러가 생길 가능성이 많다.
유지보수 하기 쉬운 코드를 작성하려면 외부에 공개되지 않는 대부분의 클래스, 인터페이스, 생성자, 메소드, 필드에 대해서도 문서화 주석을 작성해야 한다.


-
메소드의 문서화 주석에서는 메소드와 클라이언트 사이의 계약을 간명하게 설명해야 한다.


-
상속을 위해 설계된 클래스의 메소드는 계약의 설명에서 제외하되, 계약에서는 어떻게 일을 처리하는가보다 무슨 일을 하는지를 나타내야 한다.


-
문서화 주석에서는 그 메소드의 모든 사전조건(precondition)과 사후조건(postcondition)을 열거해야 한다.
일반적으로 사전조건은 unchecked 예외에 대해 @throws 태그에서 자동으로 기술되고, @param 태그의 매개 변수와 함께 설명할 수도 있다.


-
메소드의 부작용(side effect)에 대해서도 문서화해야 한다.
어떤 메소드가 백그라운드 스레드를 시작시킨다면 문서에는 그것을 기록해야 한다.


-
문서화 주석에서는 클래스나 메소드의 스레드 안정성(thread safety)를 기술해야 한다.


-
메소드의 계약 내역을 충실하게 설명하려면, 모든 매개 변수에 대한 @param 태그와 @return 태그 및 @throws 태그가 문서화 주석에 있어야 한다.
@param 태그나 @return 태그 다음에 나오는 텍스트는 매개 변수나 반환 값에 나타나는 값을 설명하는 명사구여야 한다.
@throws 태그 다음에 나오는 텍스트는 if 가 나오고 그 다음에 해당 예외가 발생하는 조건을 설명하는 문구가 나와야 한다.
@param, @return, @throws 태그 다음에 나오는 문장은 마침표(.)를 찍지 않는다.


-
{@code ...some codes... } 태그로 둘러싼 코드는 코드 폰트로 나타나며, 코드 안에 있는 HTML 이나 Javadoc 태그의 처리가 억제된다.


-
문서화 주석에 여러 라인의 코드 예를 넣으려면, HTML <pre> 태그 안에 Javadoc {@code} 태그를 집어넣으면 된다.
예를 들면 <pre>{@code 코드}</pre>


-
작다(<), 크다(>), 엠퍼샌드(&) 와 같은 HTML 메타 문자를 포함하는 문서를 생성하려면 특별한 조치가 필요하다.
가장 좋은 방법은 {@literal} 태그로 둘러싸는 것이다.
이 태그 안에 있는 HTML 이나 Javadoc 태그는 처리가 억제된다.
코드 폰트로 나타나지 않는다는 것만 다르고 나머지는 {@code} 태그와 같다.

-
각 문서화 주석의 첫 번째 문장은 그 주석이 속하는 요소의 요약 설명(summary description)이 된다.
혼선을 피하기 위해서 클래스나 인터페이스의 어떤 멤버나 생성자도 동일한 요약 설명을 가져서는 안 된다.
메소드 오버로딩의 경우에는 특히 주의해야 한다.
첫 번째 문장 설명이 같은 경우가 많기 때문이다. ( 이럼 안된다. )


-
요약 설명에 마침표(.)를 넣을 때는 주의하자.
마침표는 설명을 중단시킬 수 있기 때문이다.
마침표 다음에 공백이나 탭 또는 라인 종결자가 나오면 요약 설명이 끝나버린다.
가장 좋은 해결책은 그런 마침표가 포함된 텍스트를 {@literal} 태그로 감싸는 것이다.


-
메소드와 생성자의 경우 요약 설명은 그 메소드가 수행하는 동작을 설명하는 완전한 도구여야 한다.


-
클래스, 인터페이스, 필드의 경우 요약 설명은 명사구가 되어야 한다.


-
제네릭 타입이나 메소드를 문서화 할 때는 모든 타입 매개 변수가 문서화되었는지 확인하자.


-
enum 타입을 문서활 할 때는 타입과 public 메소드는 물론 상수들이 문서화되었는지 확인하자.


-
annotation 타입을 문서화할 때는 타입 자신은 물론 그 타입의 모든 멤버가 문서화되었는지 확인하자.


-
1.5 배포 기준으로 패키지 수준의 문서화 주석은 package.html 파일 대신 package-info.java 파일에 두어야 한다.


-
소홀히 하기 쉬운 문서화는 스레드 안전(thread-safety)와 직렬화(serializability)이다.


-
Javadoc 은 메소드 주석을 상속할 수 있다.
만일 어떤 API 요소가 문서화 주석을 갖고 있지 않다면, 그 요소가 정의된 타입과 가장 가까운 관계를 갖는 타입의 적용 가능한 문서화 주석을 찾아 가져온다. ( 메소드의 경우 시그니처 기준)
이 때 수퍼 클래스보다는 인터페이스를 먼저 찾는다.
또한 {@inheritDoc} 태그를 사용하여 수퍼 타입으로부터 문서화 주석의 일부를 상속받을 수 있다.


-
문서화 주석의 에러 가능성을 줄이는 간단한 방법은, Javadoc 이 생성한 HTML 파일을 HTML 유효성 검사기를 통해서 실행하는 것.


-
모든 외부 API 요소들의 문서화 주석은 필수적이지만, 그것만으로는 충분하지 않을 수 있다.
여러 개의 상호 연관된 클래스들로 구성되는 복잡한 API 의 경우에는 API 의 전체적인 아키텍처를 설명하는 외부 문서가 문서화 주석에 추가하여 보충될 필요가 가끔 있다.
그런 문서는 관련 클래스나 패키지의 문서화 주석에서 그 문서의 링크를 포함해야 한다.

Summary

문서화 주석은 우리 API 를 문서화하는 가장 좋고 효율적인 방법이다.
모든 외부 API 요소에 대해 문서화 주석의 사용을 반드시 고려해야 한다.
표준 규칙을 따르는 일관성 있는 스타일을 채택하자.
문서화 주석 내부에 HTML 을 사용할 수 있고, HTML 메타 문자는 반드시 이스케이프 처리해야 함을 잊지 말자.

&, 1.5, @code, @inheritdoc, @literal, @param, @pram, @return, @throws, annotation, API, background thread, Effective JAVA, enum, error prone, HTML, inheritdoc, javadoc, pacagke.html, pacakge-info.java, pirvate, postcondition, pre, pre tag, precondition, public 메소드, side effect, summary description, thread safety, unchecked, [Effective Java] 외부에 제공하는 모든 API 요소에 대해 문서화 주석을 넣자., 공백, 규칙, 마침표, 메소드, 메소드 주석, 메타 문자, 명사구, 무엇을, 문서 링크, 문서화, 문서화 주석, 백그라운드 스레드, 부작용, 사전 조건, 사전조건, 사후조건, 상속, 상속을 위해 설계된 클래스, 상수, 생성자, 선언부, 쉬운 코드, 슈퍼 클래스, 시그니처, 실망, 안정성, 어떻게, 억제, 에러, 엠퍼샌드, 오버로딩, 외부 공개, 외부에 제공하는 api, 요약 설명, 유지보수, 유효성 검사기, 인터페이스, 작다, 제네릭 타입, 주석, 직렬화, 직렬화 형태, 코드 폰트, 크다, 클래스, 타입 매개 변수, 태그, 탭, 특별한 조치, 패키지 수준 문서화 주석, 필드