接口和类方法的注释应该如何不同
在使用 C# 中的 Web 客户端软件工厂 (WCSF) 开发 ASP.net Web 应用程序时，我遇到了这种困境，同样的情况也适用于其他平台和语言。我的情况是这样的：
我基于 WCSF 范例为每个网页/用户控件定义一个 IView 接口，然后让页面类实现 IView 接口，基本上实现定义的每个方法在界面中。当我尝试在方法级别添加 xml 文档时，我发现自己基本上为接口方法及其实现类中的对应部分重复相同的注释内容。
所以我的问题是：接口方法和相应的类方法的文档内容是否应该有一些实质性的区别？他们应该强调不同的方面还是其他什么？
有人告诉我，接口方法注释应该说明该方法应该做什么“什么”，而类方法注释应该说明该方法“如何”执行。但我记得之前在某处读过，方法级别注释应该只说明方法应该做什么，而不是方法的实现细节，因为实现不应该是方法用户关心的问题，并且它可能会改变。
I ran into this dilemma when working on an ASP.net web application using Web Client Software Factory(WCSF) in C#, and the same could apply to other platform and languages. My situation is like this:
I am defining an IView interface for each web page/user control based on WCSF paradigm, then have the page class implement the IView interface, basically implementing each of the methods defined in the interface. When I tried to add xml-documentation on the method level, I found myself basically repeating the same comment content for both interface method, and its counter-part in the implementing class.
So my question is: should there be some substantial difference between the documentation content on the interface method and corresponding class method? Should they be emphasizing on different aspect or something?
Somebody told me that the interface method comment should say "what" the method is supposed to do, and the class method comment should say "how" it does it. But I remember reading somewhere before that the method level comment should only say "what" the method is supposed to do, never the implementation detail of the method, since the implementation should not be a concern for method users and it might change.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（2）
就我个人而言，我认为这些评论应该是相同的 - 用你的话来说，两者都应该说“该方法将要做什么”。
XML 注释没有理由提及实现细节。一个可能的例外是提及潜在的副作用（即：此方法可能需要很长时间），但我个人会在 XML 文档注释的
Personally, I think these comments should be the same - both should say "what the method is going to do", in your terms.
There is no reason for XML comments to mention implementation details. The one exception, potentially, would be to mention potential side effects (ie: this method may take a long time), but I personally would do that in the
<remarks>section of the XML doc comments.你可以说我是个疯子，但我会为该方法使用一个描述性名称，然后就到此为止（两者都没有评论）。如果有关它的某些事情令人惊讶或者为什么它不明显，我可能会对实现添加评论。
Call me a nut but I'd use a descriptive name for the method and call it a day (no comments for either). I might add comments to the implementation if something about it is surprising or why its there is nonobvious.