用XML注释loggingC＃代码的最佳实践是什么？
我正在通过一些我刚刚写的新代码，并将NDoc sytle注释添加到我的类和方法中。 我希望能够生成一个非常好的MSDN样式文档以供参考。
一般来说，在为一个class级和一个方法写评论时有什么好的指导方针？ NDoc评论应该说什么？ 他们不应该说什么？
我发现自己在看.NET框架的评论是什么，但是这个速度太快了; 如果我能有一些好的规则来指导自己，我可以更快地完成文档。
在用于构buildAPI文档的注释中，您应该：
-
解释方法或属性的作用，为什么它存在，并解释任何领域的概念，这些概念对于普通用户来说并不是不言而喻的。
-
列出你的参数的所有先决条件（不能为null，必须在一定范围内等）
-
列出任何可能影响调用者处理返回值的后置条件。
-
列出方法可能抛出的任何exception（以及在什么情况下）。
-
如果存在类似的方法，则解释它们之间的差异。
-
注意任何意想不到的事情（如修改全局状态）。
-
列举任何副作用，如果有的话。
如果最后的评论没有增加任何价值，那只是浪费。
例如
/// <summary> /// Gets manager approval for an action /// </summary> /// <param name="action">An action object to get approval for</param> public void GetManagerApprovalFor(Action action) …你增加了绝对没有价值，只是增加更多的代码来维护。
这些多余的注释经常被代码所淹没。
StyleCop提供代码和评论风格的提示。 它给出的build议是符合MSDN文档样式。
至于评论的内容，它应该给你的代码的用户足够的信息，以期望什么样的行为。 它也应该回答用户可能有的问题。 因此，尽量把你的代码用作对代码一无所知的人，或者甚至要求别人这么做。
对于属性，您的注释应该指出属性是只读的，只写还是读写。 如果你看所有官方的MS文档，财产文档注释总是以“获取…”，“获取或设置…”和（很less，通常避免只写属性）“设置…”
不要忘记什么是有效的XML。 例如：
/// <Summary> /// Triggers an event if number of users > 1000 /// </Summary>
（错误：无效的XML）。
我写了<summary>注释以包含我想知道的信息，如果我是调用该函数（或实例化该类）的信息。
我写了<备注>注释以包含我想知道的信息，如果我的任务是debugging或增强该function或类。 注意：这并不取代良好的内联评论的需要。 但是有时候，函数/类的内部运作的总体概述是非常有帮助的。
正如在MSDN页面上所述，您使用XML文档注释自动生成文档，因此它可以让您了解您是否正在编写API，并且不想在代码和文档中工作两次，而且还要保留它们同步 – 每次更改代码时，都会修改相应的注释并重新生成文档。
编译/doc ，编译器将search源代码中的所有XML标记，并创build一个XML文档文件，然后使用Sandcastle等工具生成完整的文档。
关于评论的一件事是更新它们。 太多的人改变一个function，然后不改变评论来反映改变。
