8장_아이템56 - ririkat/effective-java GitHub Wiki

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


💡 자바독(Javadoc)

  • java API 문서화 유틸리티
  • 소스코드 파일에서 문서화 주석으로 기술된 설명을 추려 API 문서로 변환해준다.

🔔 javadoc 주석 작성 규칙

API를 올바르게 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드 필드 선언에 문서화 주석을 달아야 한다.
  • 문서화 주석이 없다면 그저 API 요소들의 선언만 나열해주는게 전부이다.
  • 기본 생성자에는 주석을 달 수 없으므로, 공개 클래스에는 절대 기본 생성자를 사용해서는 안 된다.
  • 유지보수까지 고려한다면 공개되지 않은 클래스 ... 에도 문서화 주석을 달아야 한다.
메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다.
  • what을 기술해야 한다. (어떻게 동작하는지가 아니라 무엇을 하는지를 기술해라)
  • 메서드를 호출하기 위한 전제조건을 모두 나열해야 한다.
  • 메서드가 성공적으로 수행된 후에 만족해야 하는 사후조건도 모두 나열해라
  • 부작용도 문서화하라

    사후조건으로 명확히 나타나지는 않지만 시스템의 상태에 어떠한 변화를 가져오는 것을 뜻함.

메서드의 계약을 완벽히 기술하려면 주석 태그를 이용하여 작성해라
  • @param
    • 매개변수 설명
    • 모든 매개변수에 설명을 달아야 함.

  • @return
    • 반환 값 설명
    • 반환 타입이 void가 아니면 달아야 함.

  • @throws
    • 예외 조건 설명
    • if로 시작해 해당 예외를 던지는 조건을 설명하는 절이 뒤따름

  • {@code}
    • 주석 내에 HTML 요소나 다른 자바독 태그 무시
    • 주석에 여러 줄로 된 코드 예시를 넣으려면 {@code}를 ``태그로 감싸준다. {@code ...코드... }

  • {@literal}
    • 주석 내에 HTML 요소나 다른 자바독 태그 무시
    • {@code}와 비슷하지만 코드 폰트로 렌더링하지 않음.

  • @implSpec
    • 해당 메서드와 하위 클래스 사이의 계약 설명
    • 하위 클래스들이 그 메서드를 상속하거나 super 키워드를 이용해 호출할 때 그 메서드가 어떻게 동작하는지 명확히 인지할 수 있도록 도와줌.

  • {@inheritDoc}
    • 상위 타입의 문서화 주석 일부를 상속할 수 있음.

🔔 API 문서화에서 자주 누락되는 설명 두 가지

  • 클래스 혹은 정적 메서드가 스레드 안전하든, 그렇지 않든, 쓰레드 안전 수준을 반드시 API 설명에 포함해야 한다.
  • 직렬화할 수 있는 클래스라면 직렬화 형태로 API 설명에 기술해야 한다.

📝 핵심정리

  • 문서화 주석은 API를 문서화하는 가장 훌륭하고 횩화적인 방법이다.
  • 공개 API라면 빠짐없이 문서화 주석을 달아야 한다.
  • 표준 규약을 일관되게 지키자.
  • 문서화 주석에 임의의 HTML 태그를 사용할 수 있음을 기억하라. 단, HTML 메타문자는 특별하게 취급해야 한다.
⚠️ **GitHub.com Fallback** ⚠️