应如何接口和类方法的注释是不同的 [英] How should comments for interface and class methods be different
问题描述
我在C＃中使用Web客户端软件工厂（WCSF）的ASP.net的Web应用程序时遇到了这个难题，同样也适用于其他平台和语言。我的情况是这样的：
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 *基于WCSF范式每个网页/用户控件View接口，然后在页面类实现I *视图界面，基本实现每个接口中定义的方法。当我试图在方法层面增加了XML-文档，我发现自己基本上是重复了这两个接口的方法，其反部分在实现类相同的注释的内容。
I am defining an I*View interface for each web page/user control based on WCSF paradigm, then have the page class implement the I*View 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.
推荐答案
我个人认为，这些意见应该是相同的 - 两者都应该说什么方法是要干什么，以你的条件
Personally, I think these comments should be the same - both should say "what the method is going to do", in your terms.
没有理由对XML注释提及的实施细则。唯一例外的，潜在的，将提潜在的副作用（即：这种方法可能需要很长的时间），但我个人会做，在＆LT;说明＆GT; 的XML文档注释部分。
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.
这篇关于应如何接口和类方法的注释是不同的的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
