接口和类方法的注释应该有什么区别？

Question

我在使用C#和Web Client Software Factory(WCSF)开发ASP.net web应用程序时遇到了这个问题，其他平台和语言也可能会遇到同样的问题。我的情况是这样的：

我基于WCSF范例为每个网页/用户控件定义一个IView接口，然后让页面类实现IView接口，基本上实现了接口中定义的每个方法。当我尝试在方法级别添加xml文档注释时，我发现自己基本上在为接口方法和其在实现类中的对应方法重复相同的注释内容。

所以我的问题是：接口方法和相应的类方法之间是否应该有一些实质性的差异？它们应该强调不同的方面或其他什么吗？

有人告诉我，接口方法注释应该说清楚方法“做什么”，而类方法注释应该说清楚方法“如何”去做。但我记得之前在某个地方读到过，方法级别的注释只应该说清楚方法“做什么”，而不涉及方法的具体实现细节，因为实现不应该成为方法用户关心的问题，而且它可能会改变。

- hongliang

Answer 1

个人认为这些注释应该是相同的，都应该使用“方法将要做什么”的措辞，按照你的说法。

没有理由让XML注释提及实现细节。唯一的例外可能是提到潜在的副作用（例如，这个方法可能需要很长时间），但我个人会在XML文档注释的<remarks>部分中进行说明。

- Reed Copsey

---

这其实是我害怕的答案 :), 但我想你是对的。在两个地方重复相同的内容会让我很快疲惫。复制粘贴可以加快速度，但我这样做的事实让我感到害怕... - hongliang

@hongliang：如果你正在实现一个接口，可以获取GhostDoc的副本——它将允许你使用单个键来填写实现类的XML文档注释，并复制接口中的注释。非常流畅：http://submain.com/products/ghostdoc.aspx - Reed Copsey

哇！那正是我想要的。谢谢！ - hongliang

@ReedCopsey 你好，Reed。我之前不知道GhostDoc，所以我安装了它进行测试。我还在阅读手册/论坛，了解如何使用它。如何将接口中的注释复制到执行实现的类方法中？这在免费版本中是否可行，还是需要购买专业版？ - Filip

@Filip 当你对实现文档进行编写时，它应该自动提取接口注释（即使是在免费版本中）... - Reed Copsey

Answer 2

称我为疯子，但我会给方法命名一个描述性的名称，然后就可以了（不需要任何注释）。如果实现方式有什么令人惊讶之处或其存在的原因不明显，我可能会添加注释。

- Frank Schwieterman

---

我其实非常不同意。使用XML文档注释来进行评论方法（用简短、有意义的注释）非常有价值，特别是如果这是一个可能被其他人使用的API……从XML文档注释中获得的智能感知中的有意义的消息无可替代。 - Reed Copsey

谢谢。我同意名称应该是描述性的，这将使注释看起来似乎多余。不过，我的经验告诉我有时候，除非你不介意在名称中使用“当”和“如果”的荒谬长名称，否则你只能用名称说那么多。 - hongliang

如果调用者必须关注所调用方法的实现方式中的所有when/ifs，那么这意味着你的对象耦合度过高，需要进行设计反馈。 - Frank Schwieterman

是的，我在谈论IDispose.Dispose()。 "Perform ..." 句子来自于.NET框架IDispose.Dispose()方法的注释。我将其用作示例以显示注释可以向用户传递更多信息，因此即使方法名称本身，在这里是“Dispose”，已经具有描述性，注释仍然很有用。 - hongliang

我得同意 @reed-copsey 的不同意你。我看我的旧项目中的注释，发现更容易记住方法的作用。 - Joel