2009-04-17 84 views
95

我想我們都(當我們可以被打擾的時候!)評論我們的接口。例如評論界面,實施還是兩者?

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

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

感謝

回答

75

作爲一般規則,我用同樣的DRY(不要重複自己)的原則與代碼:

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

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

欲瞭解更多信息:

+0

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

+0

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

6

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

2

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

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

3

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

3

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

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

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

4

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

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

+0

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

0

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

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

這是在www.inheritdoc.io(免費版可用)。