구현에 Javadoc 코멘트를 추가할 필요가 있습니까?

구현에 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다른 답변에 기재되어 있는 태그는 불필요하며, 실제로는 코드의 노이즈로서 기능합니다.모든 sense 도구는 다음과 같이 슈퍼클래스 또는 인터페이스에서 메서드 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 yes를 위해 그것은 중요합니다.인터페이스만을 사용하여 구체적인 실장에 대한 참조를 선언하면 인터페이스의 메서드가 IDE에 의해 취득되기 때문에 선언되지 않습니다.

언급URL : https://stackoverflow.com/questions/3061387/should-javadoc-comments-be-added-to-the-implementation