Javadoc 주석을 구현에 추가해야합니까?

인터페이스에 Javadoc 주석을 추가하고 구현에 Javadoc이 아닌 주석을 추가하는 것이 올바른 방법입니까?

대부분의 IDE는 주석을 자동 생성 할 때 구현을 위해 비 JavaDoc 주석을 생성합니다. 구체적인 방법에 설명이 있어야하지 않습니까?

구현 전용 (재정의가 아님) 인 메서드의 경우, 특히 공용 인 경우에는 그렇지 않습니다.

재정의 상황이 있고 텍스트를 복제하려는 경우에는 절대 그렇지 않습니다. 복제는 불일치를 일으키는 확실한 방법입니다. 결과적으로 사용자는 상위 유형 또는 하위 유형에서 메소드를 검사하는지 여부에 따라 메소드에 대해 다른 이해를 갖게됩니다. @inheritDoc문서 사용 또는 제공 안 함-IDE는 Javadoc보기에서 사용할 수있는 가장 낮은 텍스트를 사용합니다.

제쳐두고, 재정의하는 버전이 상위 유형의 문서에 내용을 추가하면 문제가 발생할 수 있습니다. 박사 과정에서이 문제를 연구 한 결과 일반적으로 수퍼 타입을 통해 호출하는 경우 대체 버전의 추가 정보를 알지 못합니다.

이 문제를 해결하는 것은 내가 구축 한 프로토 타입 도구의 주요 기능 중 하나였습니다. 메소드를 호출 할 때마다 해당 대상 또는 잠재적 인 재정의 대상에 중요한 정보 (예 : 충돌 동작)가 포함되어 있는지 여부가 표시됩니다. 예를 들어,지도에 put을 호출 할 때 구현이 TreeMap 인 경우 요소를 비교할 수 있어야한다는 사실을 상기했습니다.

구현과 인터페이스 모두에 javadoc이 있어야합니다. 일부 도구를 사용하면 @inheritDoc 키워드를 사용하여 인터페이스 문서를 상속 할 수 있습니다.

/**
 * @inheritDoc
 *
 * This implementation is very slow when b equals 3.
 */
public foo(int b)
{ ... }

약간의 좋은 습관은

/**
 * {@inheritDoc}
 */

구현의 javadoc (구현 세부 사항에 대해 설명 할 추가 사항이없는 경우).

일반적으로 메서드를 재정의 할 때 기본 클래스 / 인터페이스에 정의 된 계약을 준수하므로 원래 javadoc을 어떻게 든 변경하고 싶지 않습니다. 따라서 다른 답변에서 언급 된 @inheritDoc또는 @see태그 의 사용은 필요하지 않으며 실제로 코드에서 노이즈로만 사용됩니다. 모든 현명한 도구는 여기에 지정된대로 수퍼 클래스 또는 인터페이스에서 javadoc 메소드를 상속합니다 .

Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:

- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface

일부 도구 (내가보고있는 이클립스!)는 메서드를 재정의 할 때 기본적으로 이러한 도구를 생성한다는 사실은 슬픈 상태 일 뿐이며 쓸모없는 노이즈로 코드를 복잡하게 만드는 것을 정당화하지 않습니다.

물론 재정의 메서드에 실제로 주석을 추가하려는 경우 (일반적으로 일부 추가 구현 세부 정보 또는 계약을 좀 더 엄격하게 만드는) 반대의 경우가있을 수 있습니다. 그러나이 경우 다음과 같은 작업을 거의 원하지 않습니다.

/**
 * {@inheritDoc}
 *
 * This implementation is very, very slow when b equals 3.
 */

왜? 상속 된 주석이 매우 길 수 있기 때문입니다. 이 경우 3 개의 긴 문단 끝에 추가 문장이있는 것을 누가 알아 차리게 될까요 ?? 대신 자신의 의견을 적어두면됩니다. 모든 javadoc의 도구는 항상 어떤 종류의 표시 정의 는 기본 클래스의 코멘트를 읽을하기 위해 클릭 할 수있는 링크를. 그것들을 섞는 것은 의미가 없습니다.

@see 인터페이스의 설명에 대한 링크를 생성합니다. 그러나 구현에 대한 세부 사항도 추가하는 것이 좋습니다.

Sjoerd는 인터페이스와 구현 모두에 JavaDoc이 있어야한다고 올바르게 말합니다. 인터페이스 JavaDoc은 메소드의 계약을 정의해야합니다.-메소드가 수행해야하는 작업, 필요한 입력, 리턴해야하는 값 및 오류 발생시 수행해야하는 작업.

구현 문서에는 계약에 대한 확장 또는 제한 사항과 구현, 특히 성능에 대한 적절한 세부 정보가 나와 있어야합니다.

생성 된 javadoc을 위해 예, 중요합니다. 인터페이스 만 사용하여 구체적인 구현에 대한 참조를 선언하면 IDE에서 인터페이스의 메서드를 검색하므로 그렇지 않습니다.