ITEM 56: 공개된 API 요소에는 항상 주석을 작성해라
자바독(javadoc) 유틸리티를 사용해 소스코드 파일에서 문서화 주석이라는 특수한 형태로 기술된 설명을 추려 API문서로 변환할 수 있다.
API를 올바르게 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야한다.
문서화가 제대로 갖춰지지 않은 API는 오히려 쓰기 어려워 오류의 원인이 될 수 있다.
기본 생성자에는 문서화 주석을 달 방법이 없으므로, 공개 클래스에는 기본 생성자를 사용하면 안된다.
유지보수까지 고려한다면, 공개되지 않은 클래스, 인터페이스, 생성자, 메서드, 필드에도 문서화 주석을 달아야한다.
메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이 규약을 명확하게 기술해야한다.
상속용으로 설계된 클래스의 메서드가 아니라면, 무엇(what)을 하는지 기술해야한다.
해당 메서드를 호출하기 위한 전제조건을 모두 나열해야한다.
전제 조건은
@throws태그로 비검사 예외를 선언해 암시적으로 기술@param태그로 해당 조건에 영향받는 매개변수에 기술
메서드가 성공적으로 수행된 후 만족해야하는 사후 조건도 모두 나열해야한다.
시스템의 상태에 변화를 가져오는 부작용도 기술해야한다.
ex) 백그라운드 스레드를 시작시키는 메서드
@param태그 : 모든 매개변수에 추가@return태그 : 반환 타입이void가 아니라면 필수메서드 설명과 동일한 경우 생략 가능
@throws태그 : 발생할 가능성이 있는 모든 예외에 추가문서화 주석에 HTML 태그를 사용할 수 있다. 자바독 유틸리티는 문서화 주석을 HTML로 변환하므로, HTML 요소들이 최종 문서에 반영된다.
{@code}태그태그로 감싼 내용을 코드용 폰트로 렌더링
태그로 감싼 내용에 포함된 HTML 요소나 다른 자바독 태그 무시
여러 줄로된 코드 예시는
<pre>{@code}</pre>형태로 사용
영문 문서화 주석에서 "this"는 호출된 메서드에 사용된 객체이다.
@implSpec: 해당 메서드와 하위 클래스 사이의 관계를 설명하위 클래스들이 해당 메서드를 상속하거나
super키워드 이용해 호출시 어떻게 동작하는지 명확히 설명자바 11 까지
-tag "implSpec:a:Implementation Requirements:"스위치를 켜주지 않으면@implSpec태그 무시
{@literal}태그 : HTML 마크업이나 자바독 태그 무시>,<,&등 메타문자를 포함
문서화 주석은 코드와 변환된 API문서 두군데 모두에서 읽기 쉬워야한다.
각 문서화 주석의 첫문장은 해당 요소의 요약 설명을 기술한다.
한 클래스 내에 요약 설명이 똑같은 멤버는 둘 이상이면 안된다.
요약설명
java10 이전 : 요약설명이 끝난다고 판단되는 기준은
.마침표이므로 마침표 사용시 주의마침표를 포함한 텍스트를
{@literal}로 감싸주는 것이 좋다.
java10 이후 :
{@summary}요약 설명 전용 태그 사용메서드와 생성자의 요약 설명은 해당 메서드와 생성자의 동작을 설명하는 (주어 없는) 동사구
클래스, 인터페이스, 필드의 요약설명은 대상을 설명하는 명사절
{@index}태그 : API 문서에 검색(색인) 기능 추가java9 이후 부터 사용 가능
제네릭 타입이나 제네릭 메서드 문서화시 모든 타입 매개변수에 주석을 달아야한다.
열거 타입 문서화시 상수들에도 주석을 달아야한다.
어노테이션 타입 문서화시 멤버들 모두 주석을 달아야한다.
패키지 문서화 :
pakage-info.java에 작성모듈 문서화 :
module-info.java(java9 이상 지원)클래스/정적 메서드에 스레드 안전 수준을 반디시 명시해야한다.
직렬화 클래스라면 직렬화 형태도 기술해야줘야한다.
자바독은 메서드 주석을 '상속' 가능하다.
문서화 주석이 없는 API요소 발견시 가장 가까운 문서화 주석을 찾는다.
인터페이스 > 상위 클래스 : 인터페이스가 상위 클래스보다 우선순위가 높다.
{@inheritDoc}: 상위 타입의 문서화 주석 일부를 상속할 수 있다.주석만으로 설명하지 못하는 경우 관련 클래스나 패키지에서 별도 설명 링크를 제공해주면 좋다.
java 7
-Xdoclint스위치를 켜주면, 문서를 올바르게 작성했는지 검사해주며, java8부터는 default 값이다.java9,10에서는
html5스위치를 켜면, HTML5로 만들고 기본은 HTML4이다.
Last updated