是否應該將Javadoc註釋添加到實現中？

Question

在接口中添加Javadoc註釋並在實現中添加非Javadoc註釋是否正確？

當您自動生成註釋時，大多數IDE都會爲實現生成非JavaDoc註釋。具體的方法不應該有描述嗎？

Answer 1

對於只是實現（而不是覆蓋）的方法，當然，爲什麼不呢，特別是如果它們是公共的。

如果你有一個壓倒一切的情況，你會複製任何文本，那麼絕對不是。複製是導致差異的絕對方式。因此，根據用戶是否檢查超類型或子類型的方法，用戶會對您的方法有不同的理解。使用@inheritDoc或不提供文檔 - IDE將在其Javadoc視圖中使用可用的最低文本。另外，如果您的覆蓋版本在超類型的文檔中添加了內容，那麼您可能處於一個麻煩的世界。我在博士學習期間研究了這個問題，發現一般情況下，如果人們通過父類型進行調用，人們將永遠不會意識到壓倒性版本中的額外信息。

解決這個問題是我構建的原型工具的一個主要特徵 - 每當你調用一個方法時，你就會得到一個指示，表明它的目標或任何潛在的重載目標是否包含重要信息（例如，衝突行爲）。例如，在調用放置在地圖上時，提醒您如果您的實現是TreeMap，則您的元素需要具有可比性。

Answer 2

實現和接口都應該有javadoc。使用一些工具，您可以使用@inheritDoc關鍵字繼承接口的文檔。

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

Answer 3

爲了生成javadoc yes它確實很重要。如果您僅使用接口聲明具體實現的引用，那麼它不會由於接口的方法將被IDE檢索到。

Answer 4

@see它會在界面中生成指向描述的鏈接。但我認爲也可以添加一些關於實施的細節。

Answer 5

有些好的做法是把

/** 
* {@inheritDoc} 
*/ 

爲實施的Javadoc（除非有一些額外的關於實施的細節進行闡述）。

Answer 6

Sjoerd正確地說接口和實現都應該有JavaDoc。接口JavaDoc應該定義方法的約定 - 方法應該做什麼，它需要什麼輸入，應該返回什麼值，以及在出錯時應該做什麼。

實施文檔應該注意合同的擴展或限制，以及實施的適當細節，尤其是性能。

Answer 7

通常，當你重寫一個方法時，你堅持在基類/接口中定義的契約，所以你不想改變原來的javadoc。因此，在其他答案中提到的@inheritDoc或@see標記的用法不是必需的，實際上僅用作代碼中的噪聲。

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 

，一些工具（！我看着你時，Eclipse）默認情況下重寫的方法時產生這些事實是隻有一個可悲的：按規定here所有明智的工具繼承父類或接口方法的javadoc事物的狀態，但是沒有理由用無用的噪音混淆你的代碼。

---

有當然可以是相反的情況下，如果你真的想註釋添加到壓倒一切的方法（通常是一些附加的實施細則或訂立合同有點嚴格）。但在這種情況下，你幾乎從不想這樣做：

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

爲什麼？因爲繼承的評論可能會很長。在這種情況下，誰會在3個長段落結尾處注意到額外的句子？相反，只需寫下你自己的評論，就這些了。所有的javadoc工具總是顯示某種指定的鏈接，您可以點擊閱讀基類評論。混合它們沒有意義。