使用XML注释记录C＃代码的最佳实践是什么？

Question

我正在编写一些我刚编写的新代码，并将NDoc sytle注释添加到我的类和方法中。 我希望生成一个非常好的MSDN样式文档供参考。

一般来说，在为类和方法编写注释时，有哪些好的指导原则？ NDoc评论应该说什么？ 他们应该怎么说？

我发现自己正在研究.NET框架评论所说的内容，但这种情况会变得很快; 如果我能有一些好的规则来指导自己，我可以更快地完成我的文档。

Answer 1

在用于构建API文档的注释中，您应该：

• 解释方法或属性的作用，为什么它存在，并解释任何对代码的普通消费者不言自明的域概念。

• 列出参数的所有前提条件（不能为空，必须在一定范围内等）

• 列出可能影响调用者处理返回值的任何后置条件。

• 列出方法可能抛出的任何异常（以及在什么情况下）。

• 如果存在类似的方法，请解释它们之间的差异。

• 注意任何意外的事情（例如修改全局状态）。

• 列举任何副作用，如果有的话。

Answer 2

如果您最终得到的评论不会增加任何价值，那么它们就是浪费。

例如

/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)

...你绝对没有添加任何价值，只是添加了更多代码来维护。

很多代码都充斥着这些多余的评论。

Answer 3

StyleCop提供代码和注释样式的提示。 它提供的建议符合MSDN文档样式。

至于评论的内容，它应该为您的代码的用户提供足够的信息，说明期望的行为类型。 它还应该回答用户可能遇到的潜在问题。 因此，尝试将您的代码用作对代码一无所知的人，或者甚至更好，请其他人这样做。

Answer 4

对于属性，您的注释应指示属性是只读，只写还是读写。 如果你查看所有正式的MS文档，属性文档注释总是以“获取...”，“获取或设置...”开头，并且（很少，通常避免只写属性）“设置......”

Answer 5

不要忘记什么是有效的XML。 例如：

/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>

（错误：XML无效）。

Answer 6

我编写<summary>注释以包含我想知道的信息，如果我是调用该函数的那个​​（或实例化该类）。

我编写<remarks>注释以包含我想要知道的信息，如果我负责调试或增强该函数或类。 注意：这并不能取代良好的内联注释。 但有时候对函数/类的内部工作原理的一般概述非常有用。

Answer 7

正如MSDN页面上所述，您使用XML文档注释自动生成文档，因此制造商会感觉您是否正在编写API并且不希望在代码和文档中都使用两次，并且还可以将它们保存在同步 - 每次更改代码时，都会修改相应的注释并重新生成文档。

使用/doc进行编译，编译器将在源代码中搜索所有XML标记并创建XML文档文件，然后使用Sandcastle等工具生成完整的文档。

Answer 8

关于评论的一点是更新它们。 太多人改变了一个功能，然后不改变评论以反映变化。