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이다.