Question

我想我们所有人（当我们可以被打扰时！）评论我们的界面。 e.g。

/// <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}标记从界面中“包含”javadoc。

了解更多信息：

Official javadoc documentation
一些非官方的advice。

Answer 2

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

Answer 3

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

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

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

Answer 4

我们只是评论界面，注释很容易与派生或基类/接口不同步，很高兴将它放在一个地方。

虽然看起来@Nath可能会建议一个自动化的文档工具，它可以帮助将事情保持在一起（如果您使用它，听起来很酷）。在WhereIWorkAndYouDontCare，这些评论适用于开发人员，因此首选代码中的一个位置

Answer 5

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

Answer 6

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 7

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

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

Answer 8

我创建了一个后处理XML文档文件的工具，以添加对＆lt; inheritdoc /＆gt;的支持。标签

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

请访问www.inheritdoc.io（免费版）。

Answer 9

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

评论界面，实现或两者？

9 个答案: