代码注释：您是否将代码注释放在接口或具体类上，或两者都放在一起？
记录类和接口的最佳实践是什么？假设您有一个名为 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();
}
What is the best practice in documenting classes and interfaces. Say if you have a concrete class called Foo, that derives from an interface called IFoo. Where do you put your comments for your methods? Do you duplicate your comments on the Interface as well as the concrete class?
Here is an example where comments are duplicated:
public class Foo : IFoo
{
/// <summary>
/// This function does something
/// </summary>
public void DoSomething()
{
}
}
public interface IFoo
{
/// <summary>
/// This function does something
/// </summary>
void DoSomething();
}
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（9）
我会对两者发表评论。
在接口上，我会评论接口成员和用法背后的意图。
关于实现，我会评论一下具体实现的原因。
I would put comments on both.
On interfaces I would comment on the intent behind the interface members and usage.
On implementations I would comment on the reasons for the specific implementation.
我把它们都放进去了，但保持它们同步很痛苦，当有疑问时，我只把它们放在界面上。
我这样做是因为我喜欢使用代码时的工具提示，它几乎应该总是使用界面......
I put them in both, but its a pain keeping them in sync, when in doubt I only put them on the interface.
I do this because I like the tooltip when using the code, which should almost always be using the interface...
我通常把它们放在两者上，但是，它们说的并不是同一件事。接口的注释应该描述该方法/接口的抽象目的。而具体注释将在接口用途的上下文中讨论方法/类的实现细节。
I generally put them on both, however, they do not say the same thing. The interface's comment should describe the abstract purpose of this method/interface. While the concrete comment will talk about the implementation specifics of the method/class in the context of the interface's purpose.
您的示例代码不使用显式接口实现。代码的客户端将需要两者，因为他/她可以通过类对象或接口引用调用该方法。通过显式接口实现，您可以省略类方法注释，因为客户端永远看不到它。假设您正在使用 XML 文档来生成 IntelliSense 信息。
Your example code doesn't use explicit interface implementation. The client of your code is going to need both since s/he can invoke the method either through a class object or interface reference. With explicit interface implementation you can omit the class method comment since the client can never see it. This is assuming you are using XML documentation to generate IntelliSense info.
仅适用于接口。因为在这种情况下我不需要同步它们。我的 IDE 帮助我查看具体类中的接口注释。 api 文档生成器也做同样的事情。
Only for interfaces. Because in this case I don't need to synchronize them. My IDE helps me to see interface comments in concrete classes. And api document generator does the same.
两者都有，但我希望有内置功能来保持它们同步
Both, but I wish there was built in functionality to keep them in sync
标签
System。 .... A tag
<referTo>System. .... </referTo>to link the comments would be ideal理想情况下，只需要记录接口，因为它定义了每个具体实现需要履行的契约。
Ideally, only the interface needs to be documented, since it defines the contract that every concrete implementation needs to fulfill.
我根本不使用它们。相反，我确保构建代码并命名所有方法和变量，使其在没有注释的情况下显而易见。注释的问题在于它们不编译、不执行并且不通过单元测试进行测试，因此几乎不可能使它们与代码保持同步。
I don't really use them at all. Instead I make sure to structure the code and name all methods and variables in a way that its obvious what they do without comments. The problem with comments is that they don't compile and don't execute and are not tested by your unit tests, so its pretty much impossible to keep them in synch with the code.