자바독(Javadoc)

• 소스코드 파일에서 자바독 주석이라는 특수한 형태로 기술된 설명을 API 문서로 변환해줌
• Java 언어로 작성된 소스 코드에 대한 문서를 HTML 형식으로 생성하는 도구
• 클래스, 인터페이스, 메소드, 필드 등에 대한 설명을 제공

공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달자

• 기본 생성자에는 문서화 주석을 달 방법이 없으니 공개 클래스는 절대 기본 생성자를 사용하지 말자
• 유지보수까지 고려한다면 대다수의 공개되지 않은 클래스, 인터페이스, 생성자, 메서드, 필드에도 문서화 주석을 달자
• 메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술하자
  • 메서드가 어떻게 동작하는지를 적는 게 아니라 무엇을 하는지 기술
  • 클라이언트가 해당 메서드를 호출하기 위한 전제조건(precondition)을 모두 나열
  • 메서드가 성공적으로 수행된 후에 만족해야 하는 사후조건(postcondition)을 모두 나열
  • 부작용(사후조건으로 명확하게 나타나지는 않지만 시스템의 상태에 어떠한 변화를 가져오는 것)도 문서화

주석 규칙

메서드 문서화 주석 규칙

• 모든 매개변수에 @param
• 반환 타입이 void가 아니라면 @return 태그
• 발생할 가능성이 있는 모든 예외에는 @throw 태그

  /**
     * Returns the element at the specified position in this list. 
     *
     * <p>This method is <i>not</i> guaranteed to run in constant
     * time. In some implementations it may run in time proportional
     * to the element position.
     *
     * @param  index index of element to return; must be
     *         non-negative and less than the size of this list
     * @return the element at the specified position in this list
     * @throws IndexOutOfBoundsException if the index is out of range
     *         ({@code index < 0 || index >= this.size()})
     */
    E get(int index) {
        return null;
    }

상속용 클래스 문서화 주석 규칙

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