评论接口、实现还是两者兼而有之？

Posted 2023-02-21

技术标签:

【中文标题】评论接口、实现还是两者兼而有之？【英文标题】：Comment the interface, implementation or both? 【发布时间】：2010-10-20 01:41:33 【问题描述】：

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

/// <summary>
/// Foo Interface
/// </summary>
public interface Foo

    /// <summary>
    /// Will 'bar'
    /// </summary>
    /// <param name="wibble">Wibble factor</param>
    void Bar(string wibble);

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

谢谢

【问题讨论】：

复制品偷偷溜过这里：***.com/questions/1875440/… 【参考方案1】：

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

【讨论】：

这仅适用于方法。课堂上的InheritDoc 将显示Object 的文档。【参考方案2】：

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

【讨论】：

【参考方案3】：

我创建了一个对 XML 文档文件进行后处理以添加对标签的支持的工具。

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

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

【讨论】：

请注意，Sandcastle 帮助文件生成器也支持，并在此处记录：ewsoftware.github.io/XMLCommentsGuide/html/…。刚刚发现上面也提到了这个。【参考方案4】：

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

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

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

更多信息：

Official javadoc documentation 一些非官方的advice。

【讨论】：

非常感谢您提供有关@inheritDoc 标签的信息对于C#，可以使用<inheritdoc />，SandCastle 支持。 (More info...) 仅在接口上指定时，继承类中的属性和其他元素不会在工具提示中显示 XML 文档。对于同一个类的外部使用，它是可见的。这可能是 Visual Studio 2015 的一个错误。这是为 Sandcastle/SHFB inheritdoc 页面提供的链接 @Virtlink 的更新版本：ewsoftware.github.io/XMLCommentsGuide/html/… 似乎适用于 C# 中的 Visual Studio 2019。如果您使用它，智能感知将显示来自界面的评论。【参考方案5】：

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

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

【讨论】：

不自动，需要用户操作，很遗憾。【参考方案6】：

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

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

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

【讨论】：

【参考方案7】：

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

【讨论】：

【参考方案8】：