使用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无效).