評論界面，實施還是兩者？

我想我們都（當我們可以被打擾的時候！）評論我們的接口。例如評論界面，實施還是兩者？

/// <summary> 
/// Foo Interface 
/// </summary> 
public interface Foo 
{ 
    /// <summary> 
    /// Will 'bar' 
    /// </summary> 
    /// <param name="wibble">Wibble factor</param> 
    void Bar(string wibble); 
}

您是否也評論實施（也可能提供給客戶，例如作爲圖書館的一部分）？如果是的話，你如何管理保持兩者同步？或者你只是添加一個'看文檔的界面'評論？

感謝

來源

2009-04-17 ng5000

作爲一般規則，我用同樣的DRY（不要重複自己）的原則與代碼：

上接口，文件接口
實現，文件的執行細節

Java的具體：記錄的執行情況時，使用{} @inheritDoc標籤「包括」的javadoc˚F從界面。

欲瞭解更多信息：

Official javadoc documentation
一些非官方advice。

來源

2009-04-17 09:27:46

很感謝我對@inheritDoc標記不知道的信息 – 2009-04-17 10:17:17

哇......我不知道{@inheritDoc}是否存在！我將從今天起定期使用它。 – mcherm 2010-07-02 17:07:46

如果使用GhostDoc插件，它更新與從接口註釋實施當你右擊並選擇方法「文檔本」。

來源

2009-04-17 09:21:28 NikolaiDante

評論接口應該有足夠的文檔來弄清楚如何使用實際的實現。唯一一次我會爲實現添加註釋的是，它具有爲了滿足接口而插入的私有函數，但是它們只是內部的註釋，並且不會在網上的文檔中看到或者可以提供給客戶。

實現就是這樣，只要它們符合接口，就不需要單獨記錄它們。

來源

2009-04-17 09:23:32

僅限界面。評論兩者都是重複的，如果代碼改變，這兩組評論最終可能會失去同步。使用「implements MyInterface」評論實現......像Doxygen這樣的東西將生成包含派生文檔的文檔（如果您正確設置它們），請將文檔包含在實現文檔中。

來源

2009-04-17 09:26:07

對於C＃它取決於IMO：如果您使用顯式接口實現，那麼我不會記錄實現。

但是，如果直接實現接口並將接口的成員公開給對象，那麼這些方法也必須記錄下來。

正如Nath所說，您可以使用GhostDoc自動將接口的文檔插入到實現中。我將文檔這個命令映射到Ctrl + Shift + D快捷鍵和我幾乎自動按下的其中一個擊鍵。我相信ReSharper也可以選擇插入接口的文檔，當它實現你的方法。

來源

2009-04-17 09:26:42 grover

我們只是評論界面，評論很容易與派生或基類/界面不同步，這是很好，只有在一個地方。

雖然它看起來像@Nath可能暗示了一個自動化的文檔工具，可以幫助保持在一起（聽起來很酷，如果你使用它）。在這裏，在WhereIWorkAndYouDontCare的評論是用於開發所以在代碼一個地方最好

來源

2009-04-17 09:27:46 Jiminy

不自動，不幸的是需要用戶操作。 – NikolaiDante 2009-04-17 10:01:57

我創建了一個後處理XML文檔文件的工具，以添加對< inheritdoc/>標記的支持。

雖然它對源代碼中的Intellisense沒有幫助，但它確實允許將修改的XML文檔文件包含在NuGet包中，因此可以在引用的NuGet包中使用Intellisense。

這是在www.inheritdoc.io（免費版可用）。

來源

2017-12-21 00:19:11

評論界面，實施還是兩者？

回答

相關問題