如果它們實現的接口具有JavaDoc注釋，那么實現方法是否應該有JavaDoc注釋

Question

假設我有一個如下界面。

public interface MyInterface{

 /**
 * This method prints hello
 */
  void sayHello();

  /**
  * This method prints goodbye
  */
  void sayGoodBye();
}

具體類實現這些方法。 現在，具體類中的方法是否還需要在其方法定義之上定義javadoc？ 我看到有些人只是將相同的javadoc定義復制到具體類的實現方法中。 我不認為這是一個好習慣，因為如果我們要更改文檔定義，我們需要在多個地方更改它。

這是什么標准做法？

Answer 1

您可以使用{@inheritDoc}繼承接口的文檔，如果您認為它們是特定實現的重要且相關的額外信息，則只需添加額外的注釋。

如果要添加到原始超類/接口文檔，請僅使用@inheritDoc 。 如果您只想要一份副本，Javadoc將負責處理。 它將看到超類文檔適用於子類的重寫方法，因為子類沒有提供其他文檔。

{@inheritDoc} - 將文檔從“最近的”可繼承類或可實現的接口繼承（復制）到此標記位置的當前文檔注釋中。 這允許您在繼承樹的更高位置編寫更多通用注釋，並在復制的文本周圍編寫。

http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#@inheritDoc

Answer 2

現在，具體類中的方法是否還需要在其方法定義之上定義javadoc？

不，它已經指定了。 具體的方法應該完全與Javadoc所說的接口完全不同。

我看到有些人只是將相同的javadoc定義復制到具體類的實現方法中。 我不認為這是一個好習慣，因為如果我們要更改文檔定義，我們需要在多個地方更改它。

你是對的。 他們不應該這樣做。

你也不應該使用@inheritDoc ，除非極少數情況下具體方法需要比Javadoc接口更多的描述。 大多數時候你根本不應該提供任何Javadoc，甚至不提供：

/**
 *
 */

Answer 3

如果是，您應該為具體實施提供評論

• 接口的注釋是如此通用，它沒有充分說明具體的實現
• 具體實現放寬了界面的任何前提條件
• 具體實現具有比界面更嚴格（更窄）的后置條件。