代码注释：您是否将代码注释放在接口或具体类上，或两者兼而有之？ [复制]答案

【问题标题】：Code Commenting: Do you put your code comments on Interfaces or on Concrete classes, or both? [duplicate]代码注释：您是否将代码注释放在接口或具体类上，或两者兼而有之？ [复制]
【发布时间】：2010-12-24 22:19:12
【问题描述】：

记录类和接口的最佳实践是什么。假设您有一个名为 Foo 的具体类，它派生自一个名为 IFoo 的接口。你把你的 cmets 放在哪里？您是否在接口和具体类上复制您的 cmets？

这里是一个 cmets 重复的例子：

public class Foo : IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    public void DoSomething()
    {
    }
}

public interface IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    void DoSomething();
}

【问题讨论】：

标签： c# comments xml-comments

【解决方案1】：

我通常将它们放在两者上，但是，它们说的不是同一件事。接口的注释应该描述这个方法/接口的抽象目的。而具体的评论将在接口用途的上下文中讨论方法/类的实现细节。

【讨论】：

【解决方案2】：

我把它们都放在了，但是让它们保持同步很痛苦，当有疑问时我只把它们放在界面上。

我这样做是因为我喜欢使用代码时的工具提示，它应该几乎总是使用界面...

【讨论】：

【解决方案3】：

我会把 cmets 放在两者上。

关于接口，我会评论接口成员和用法背后的意图。

关于实现，我会评论具体实现的原因。

【讨论】：

+1 ...如果您使用的是 GhostDoc，很容易将接口 cmets 从接口成员复制到它们的具体实现。

【解决方案4】：

我根本不使用它们。相反，我确保以一种显而易见的方式构建代码并命名所有方法和变量，而不用 cmets。 cmets 的问题是它们不编译也不执行，也没有经过单元测试的测试，因此几乎不可能使它们与代码保持同步。

【讨论】：

这些 cmets 更多地用于 Intellisence，然后用于理解代码。我同意它们更难维护，但它们对于探索 API 非常有帮助。
嘿，我想它们在您为来自不同团队的人开发 API 时很有用。

【解决方案5】：

仅适用于接口。因为在这种情况下我不需要同步它们。我的 IDE 帮助我查看具体类中的接口 cmets。 api 文档生成器也是如此。

【讨论】：

【解决方案6】：

两者都有，但我希望有内置功能让它们保持同步

【讨论】：

【解决方案7】：

您的示例代码未使用显式接口实现。您的代码的客户端将需要两者，因为他/她可以通过类对象或接口引用调用该方法。使用显式接口实现，您可以省略类方法注释，因为客户端永远看不到它。这是假设您使用 XML 文档来生成 IntelliSense 信息。

【讨论】：

【解决方案8】：

一个标签<referTo>System. .... </referTo> 来链接cmets 是理想的

【讨论】：

【解决方案9】：

理想情况下，只需要记录接口，因为它定义了每个具体实现都需要履行的契约。

【讨论】：