이펙티브 자바, 쉽게 정리하기 - item 56. 공개된 API 요소에는 항상 문서화 주석을 작성하라

이펙티브 자바, 쉽게 정리하기 - item 56. 공개된 API 요소에는 항상 문서화 주석을 작성하라

API 문서화 관련 지침

자바독을 이용하자.

• 자바독을 최대한 활용한다.
  • 자바독 태그인 @literal, @code, @implSpec, @index (java9) 를 이용하자.

{@literal}

• 주석 내에 HTML 요소나 다른 자바독 태그를 무시함
  • 글자 그대로 쓸 때 필요

{@code}

• {@literal} 과 비슷한데, 코드 폰트로 렌더링한다.

@implSpec

• 해당 메서드와 하위 클래스 사이의 계약을 설명
• 하위 클래스가 해당 메서드를 상속했거나, super 키워드를 이용해 호출할 때 메서드가 어떻게 동작할지 명확히 인지할 수 있게 도와준다

필수적으로 들어가야 하는 것들

• 모든 공개된 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 다는 것이 좋다.
• 직렬화, 동기화에 대한 내용은 되든 안되든 꼭 담자
• 메서드용 문서화 주석에는 메서드와 클라이언트 사이의 규약을 명확히 기술하자.
  • 메서드 문서화 주석에는 구현 내용인 어떻게 (How) 가 아닌 무엇을 (What) 이 들어가는 것이 좋다.
  • @param, @return, @throws 로 파라미터, 반환값, 예외를 잘 명시해주자
  • 그 외 실행 전 전제 조건 (pre-condition), 실행 후 사후조건, 부작용 (side-effect) 등은 반드시 문서화하는 것이 좋다.
    • @throws 태그로 비검사 예외를 선언하거나, @param 태그로 조건에 영향받는 매개변수에 기술할 수도 있다.
    • 부작용은 이를테면 백그라운드 스레드를 실행시키는 경우 꼭 명시해야 한다.

각종 태그 사용법

• @태그 의 설명에는 문장보다는 명사구를 쓰는 것이 좋으며 보통 마침표를 붙이지 않는다.
• @태그 를 주석에 넣을 때는 @code 의 경우 <pre>{@code index==1}</pre> 과 같이 작성하면 된다.
• 영문 주석의 this 는 호출된 메서드가 자리하는 객체를 가리킨다.
• 상속용으로 클래스 설계 시에는 @implSpec 과 같은 태그를 이용하여 자기 사용에 대한 패턴도 문서화해주어야 한다.
• HTML에서 사용하는 <, >, & 등의 문자를 그냥 사용하고 싶다면 @{literal } 태그로 감싸주자.

요약 설명

• 각 문서화 주석의 첫번째 문장은 해당 요소의 요약설명으로 간주된다.
• 요약 설명은 반드시 대상의 기능을 고유하게 기술해야 한다.
• 한 클래스(혹은 인터페이스) 안에 요약 설명이 똑같은 멤버(혹은 생성자)가 둘 이상이면 안된다.
• 요약 설명은 처음 발견되는 {마침표, 공백, 다음 문장 시작} 패턴의 마침표까지이므로 주의하자.
  • 요약 설명으로 인한 마침표 사용이 아닐 때는 @{literal} 을 이용해 명확히 해주자.
• 일반적으로 요약 설명은 완전한 문장으로 작성하지 않는다.
• 영어의 경우 3인칭 동사로 시작하는 불완전한 문장이 온다.

제네릭, 열거, 애너테이션

제네릭의 경우

• 모든 제네릭 타입 매개변수에 주석을 달아야 한다.

열거의 경우

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

애너테이션의 경우

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

패키지 설명 문서화 주석

• package.info.java 파일에 작성한다.

메서드 주석 상속 기능

• 문서화 주석이 없는 API 요소를 발견하면, 자바독이 가장 가까운 문서화 주석을 찾아준다.
  • 상위 '클래스'보다 클래스가 구현한 '인터페이스'를 먼저 찾는다.
• {@inheritDoc} 태그를 사용해 상위 타입의 문서화 주석 일부를 상속할 수 있다.
  • 클래스는 자신이 구현한 인터페이스의 문서화 주석을 재사용할 수 있다.

복잡한 API의 주석을 작성할 때

• 너무 설명하기 복잡한 API라면 관련 링크를 달아주는 것도 좋다.

핵심 정리

• 공개 API라면 문서화를 잘하고 일관된 규칙을 지키자.
• 문서화 주석에 HTML과 각종 문서화 태그를 사용할 수 있음을 기억하고, 잘 활용하자.