item 56 공개된 API 요소에는 항상 문서화 주석을 작성하라

ITEM 56 공개된 API 요소에는 항상 문서화 주석을 작성하라

---

API를 쓸모 있게 하려면 잘 작성된 문서도 곁들여야 한다

• 전통적으로 API 문서는 사람이 직접 작성하므로 코드가 변경되면 매번 함께 수정해야줘야 한다
• 하지만 자바에서는 자바독을 이용하면 소스코드 파일에서 문서화 주석이라는 특수한 형태로 기술된 설명을 추려 API문서로 만들어준다

문서화 주석을 작성하는 규칙은 공식 언어 명세에 속하진 않지만 자바 프로그래머라면 응당 알아야 하는 업계 표준 API라 할 수 있다

• API를 똑바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 무선화 주석을 달아야 한다
  • 직렬화 할 수 있는 클래스면 직렬화 형태에 관해서도 적어야한다
  • 기본 생성자에는 문서화 주석을 달 수 없으니 공개 클래스에선 사용하지 말자
  • 유지보수까지 고려하면 대부분의 공개되지 않은 클래스, 인터페이스, 생성자, 메서드, 필드에 문서화 주석을 달자
• 메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다
  • 상속용으로 설계된 클래스의 메서드가 아니라면 메서드가 어떻게 동작하는지가 아닌 무엇을 하는지 작성하자
  • 문서화 주석에는 클라이언트가 해당 메서드를 호출하기 위한 전제조건을 모두 나열해야 한다
    • 메서드가 성공적으로 수행된 후에 만족해야 하는 사후조건도 모두 나열해야 한다
  • 부작용도 문서화 해야한다
    • 부작용은 사후조건으로 명확하게 나타나지 않지만 시스템의 상태에 변화를 가져오는 것
  • 메서드의 계약(contract)을 완벽하게 작성하려면 모든 매개변수에 @param 태그를 작성하고 반환 타입이 void가 아니라면 @return 태그를, 발생할 가능성이 있는 모든 예외에 @throws 태그를 달아야 한다
• 자바독 유틸리티는 문서화 주석을 HTML로 변환하기 때문에 문서화 주석 안의 HTML 요소들이 최종 HTML 문서에 반영된다
• 각 문서화 주석의 첫 번째 문장은 해당 요소의 예약 설명으로 간주된다
  • 요약 설명은 반드시 대상의 기능을 고유하게 기술해야 하며 한 클래스나 인터페이스 안에서 요약 설명이 똑같은 멤버나 생성자가 둘 이상이면 안 된다
  • 다중 정의된 메서드가 있다면 더 조심하자
  • 요약 설명에서는 마침표가 끝나는 판단 기준이니 마침표에 주의하자
  • 의도치 않은 마침표를 포함한 텍스트라면 {@literal}로 감싸주자
  • 2인칭 문장이 아닌 3인칭 문장으로 작성하며 클래스, 인터페이스, 필드의 요약 설명은 대상을 설명하는 명사절이어야 한다
    • 클래스와 인터페이스의 대상은 그 인스턴스이고 필드의 대상은 필드 자신이다
• 제네릭 타입이나 제네릭 메서드를 문서화할 때는 모든 타입 매개변수에 주석을 달아야 한다
• 열거 타입을 문서화할 때는 상수들에도 주석을 달아야 한다
  • 열거 타입 자체와 그 열거 타입의 public 메서드도 포함이며 설명이 짧다면 주석 전체를 한 문장으로 써도 된다
• 애너테이션 타입을 문서화할 때는 멤버들에도 모두 주석을 달아야 한다
  • 애너테이션 타입 자체도 달며 필드 설명은 명사구로 한다
  • 애터네테이션 타입의 요약 설명은 애너테이션을 다는 의미를 동사구로 쓴다
• 클래스 혹은 정적 메서드가 스레드 안전하든 그렇지 않든 스레드 안전 수준을 반드시 API 설명에 포함해야 한다
  • 직렬화 할 수 있는 클래스라면 직렬화 형태도 API 설명에 작성해야한다

문서화 주석은 API를 문서화하는 가장 훌륭하고 효과적인 방법이다

공개 API라면 빠짐없이 설명을 달아야 하며 표준 규약을 일관되게 지키자

문서화 주석에 임의의 HTML 태그를 사용 가능하지만 HTML 메타문자는 특별하게 취급해야 한다