评论界面，实现或两者？

我想象我们所有人（当我们可以打扰的时候！）评论我们的界面。例如

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

您是否还评论了实现（它也可以提供给客户，例如作为aa库的一部分）？如果是这样，您如何管理两者同步？还是只添加“查看文档界面”注释？

谢谢

作为一般规则，我使用与代码相同的DRY（不重复自己）原理：

• 在界面上，记录界面
• 在实施过程中，记录实施细节

特定于Java的文档：在记录实现时，请使用{@inheritDoc}标记从界面“包括” javadocs。

想要查询更多的信息：

• 官方JavaDoc文档
• 一些非正式的建议。

如果使用GhostDoc加载项，则在右键单击并在方法上选择“将此文档记录”时，它将使用界面中的注释更新实现。

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

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

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

仅接口。注释两者都是重复的，并且如果代码更改，则两组注释最终可能最终不同步。用“ implements MyInterface”（注释实现MyInterface）注释实现。Doxygen之类的东西会生成将派生文档包括在实现文档中的文档（无论如何正确设置）。

我们仅对接口进行注释，注释很容易与派生类或基类/接口不同步，因此只需将其放在一个位置就很好了。

虽然看起来像@Nath，但可能建议您使用一种自动化的文档工具来帮助将所有东西保持在一起（如果使用它，声音听起来很酷）。这里的whereIWorkAndYouDontCare注释是针对开发人员的，因此首选代码中的单个位置

对接口进行注释应该足够说明如何使用实际实现的文档。我唯一要向实现中添加注释的情况是，它是否已插入满足接口的私有功能，但是它们仅是内部注释，不会在联机文档中显示或可供客户使用。

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

我创建了一个对XML文档文件进行后处理的工具，以添加对<inheritdoc />标记的支持。

尽管它对源代码中的Intellisense没有帮助，但它确实允许将修改后的XML文档文件包含在NuGet包中，因此可以在引用的NuGet包中与Intellisense一起使用。

它位于www.inheritdoc.io（提供免费版本）。

您当然可以对两者都进行注释，但是这样就存在维护两者的问题（如前所述）。但是，在当今时代，是否有任何消耗代码真的不会使用IoC / DI而不使用接口？鉴于此，如果您只想打扰评论者，我强烈建议您评论界面。这样，代码的使用者很可能会获得漂亮的智能提示。

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();
    }
}