C# 评论接口、实现或两者？

Comment the interface, implementation or both?

提问by ng5000

I imagine that we all (when we can be bothered!) comment our interfaces. e.g.

我想我们所有人（当我们可能会被打扰时！）评论我们的界面。例如

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

Do you also comment the implementation (which may also be provided to clients, e.g. as part of a a library)? If so how do you manage keeping the two in sync? Or do you just add a 'See interface for documentation' comment?

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

Thanks

谢谢

采纳答案by Neeme Praks

As a general rule, I use the same DRY (Don't Repeat Yourself) principle as with code:

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

• on interface, document the interface
• on implementation, document the implementation specifics

• 在界面上，记录界面
• 关于实施，记录实施细节

Java specific: when documenting the implementation, use {@inheritDoc} tag to "include" javadocs from the interface.

Java 特定：在记录实现时，使用 {@inheritDoc} 标记从接口“包含”javadoc。

For more information:

想要查询更多的信息：

• Official javadoc documentation
• Some unofficial advice.

• 官方 javadoc 文档
• 一些非官方的建议。

回答by NikolaiDante

If you use the GhostDocaddin, it updates the implementation with the comment from the interface when you right click and select "Document This" on the method.

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

回答by X-Istence

Commenting the interface should be enough documentation to figure out how to use the actual implementation. The only time that I would add comments to the implementation is if it has private functions that were inserted to satisfy the interface, however they would be internal only comments and would not be seen in documentation online or available to clients.

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

Implementations are just that, as long as they conform to the interface there is no need to document them separately.

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

回答by Len Holgate

The interface only. Commenting both is duplication and it's likely that the two sets of comments will eventually get out of sync if the code changes. Comment the implementation with "implements MyInterface"... Things like Doxygen will generate docs that include the derived docs into the docs for the implementation anyway (if you set them up correctly).

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

回答by grover

For C# it depends IMO: If you use explicit interface implementations, then I wouldn't document the implementation.

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

However if you implement the interface directly and expose the members of the interface with your object then these methods must be documented too.

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

As Nath said, you can use GhostDoc to automatically insert the documentation of an interface into the implementation. I mapped the Document This command to the Ctrl+Shift+D shortcut and its one of the keystrokes I almost automatically press. I believe ReSharper also has the option to insert the documentation of the interface, when it implements the methods for you.

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

回答by Jiminy

We just comment the interface, comments are so easy to get out of sync with either the derived or base class/interface that's it's nice to have it in just one place.

我们只是对接口进行注释，注释很容易与派生类或基类/接口不同步，因此将它放在一个地方很好。

Although it looks like @Nath maybe suggesting an automated documentation tool that helps keep things together (sounds cool if you use that). Here at WhereIWorkAndYouDontCare the comments are for dev so a single place in the code is preferred

尽管看起来@Nath 可能会建议使用一种有助于将事物保持在一起的自动化文档工具（如果您使用它听起来很酷）。在 WhereIWorkAndYouDontCare 中，注释适用于开发人员，因此首选代码中的单个位置

回答by K Johnson

I created a tool that post-processes the XML documentation files to add support for the <inheritdoc/> tag.

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

While it doesn't help with Intellisense in source code, it does allow the modified XML documentation files to be included in a NuGet package and therefore works with Intellisense in referenced NuGet packages.

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

It's at www.inheritdoc.io (free version available).

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

回答by bytedev

You can certainly comment both but then you have the problem of maintaining both (as previously mentioned). However, in this day and age is any consuming code really not going to be using IoC/DI and not use the interface? Given this if you only want to bother commenting one I would strongly suggest commenting the interface. This way the consumer of your code will more than likely get the nice intellisense hints.

您当然可以对两者都发表评论，但是您会遇到维护两者的问题（如前所述）。然而，在这个时代，任何消耗代码真的不会使用 IoC/DI 而不使用接口吗？鉴于此，如果您只想打扰评论一个，我强烈建议评论界面。通过这种方式，您的代码的使用者很可能会得到很好的智能提示。

回答by Raghav

C# usage:

C#用法：

Interface can look like this:

界面可以是这样的：

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

Implementation can look like this:

实现可以是这样的：

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