评论界面,实现或两者？

Question

我想我们所有人(当我们可以被打扰时!)评论我们的界面.例如

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

您是否也评论实施(也可能提供给客户,例如作为图书馆的一部分)？如果是这样,你如何管理保持两者同步？或者您只是添加"查看文档界面"评论？

谢谢

Answer 1

作为一般规则,我使用与代码相同的DRY(不要重复自己)原则:

• 在界面上,记录界面
• 在实施方面,记录实施细节

特定于Java:在记录实现时,使用{@inheritDoc}标记从接口"包含"javadocs.

欲获得更多信息:

• 官方javadoc文档
• 一些非正式的建议.

Answer 2

C#用法：

界面可以是这样的：

    /// <summary>
    /// Helper class to access various properties for the current site.
    /// </summary>
    public interface ISiteHelper
    {
        /// <summary>
        /// Gets the site id of the current site
        /// </summary>
        /// <returns>The site id.</returns>
        int GetSiteID();
    }
}

实现可以是这样的：

/// <inheritdoc />
public class SiteHelper: ISiteHelper
{
    /// <inheritdoc />
    public int GetSiteID()
    {
        return CommonRepository.GetSiteID();
    }
}

Answer 3

如果您使用GhostDoc插件,当您右键单击并在方法上选择"Document This"时,它会使用界面中的注释更新实现.

Answer 4

界面而已。对两者都进行注释是重复的，如果代码发生变化，这两组注释很可能最终会失去同步。用“implements MyInterface”评论实现......像Doxygen这样的东西会生成文档，这些文档将派生文档包含到实现文档中（如果你正确设置了它们）。

Answer 5

注释接口应该有足够的文档来弄清楚如何使用实际的实现。我向实现添加注释的唯一一次是它是否具有插入以满足接口的私有函数，但是它们只是内部注释，不会在在线文档中看到或可供客户使用。

实现就是这样，只要它们符合接口，就不需要单独记录它们。

Answer 6

对于C＃，它取决于IMO：如果您使用显式接口实现，那么我将不记录实现。

但是，如果直接实现接口并用对象公开接口的成员，那么这些方法也必须记录在案。

正如Nath所说，您可以使用GhostDoc将接口的文档自动插入到实现中。我将此文档映射到Ctrl + Shift + D快捷键及其几乎自动按下的击键之一。我相信ReSharper在为您实现方法时也可以选择插入接口的文档。