代码注释：您是否将代码注释放在Interfaces或Concrete类上，或两者兼而有之？

Question

记录类和接口的最佳做法是什么。假设您有一个名为Foo的具体类，它派生自一个名为IFoo的接口。你在哪里提出你的方法评论？您是否在界面以及具体类上复制了您的注释？

以下是评论重复的示例：

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

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

Answer 1

我会对两者发表评论。

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

在实施时，我会评论具体实施的原因。

Answer 2

我通常把它们放在两者上，然而，他们并没有说同样的话。接口的注释应描述此方法/接口的抽象目的。虽然具体的注释将在接口的目的上下文中讨论方法/类的实现细节。

Answer 3

我把它们放在两者中，但是让它们保持同步是一种痛苦，当有疑问时我只把它们放在界面上。

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

Answer 4

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

Answer 5

两者，但我希望内置的功能可以使它们保持同步

Answer 6

用于链接评论的标记<referTo>System. .... </referTo>是理想的

Answer 7

我根本不使用它们。相反，我确保构造代码并以一种明显的方式命名所有方法和变量，而没有注释。注释的问题在于它们不能编译而且不执行，并且不会通过单元测试进行测试，因此几乎不可能使它们与代码保持同步。

Answer 8

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

Answer 9

理想情况下，只需要记录接口，因为它定义了每个具体实现需要实现的合同。