9

记录类和接口的最佳实践是什么。假设您有一个名为 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();
}
4

9 回答 9

19

我会对两者发表评论。

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

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

于 2009-12-09T17:23:39.613 回答
4

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

于 2009-12-09T17:20:47.200 回答
4

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

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

于 2009-12-09T17:21:34.577 回答
3

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

于 2009-12-09T17:29:03.350 回答
2

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

于 2009-12-09T17:24:25.837 回答
2

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

于 2009-12-09T17:25:11.707 回答
2

链接评论的标签<referTo>System. .... </referTo>将是理想的

于 2009-12-09T17:46:52.910 回答
2

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

于 2009-12-09T17:50:01.053 回答
1

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

于 2009-12-09T17:24:14.557 回答