用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,然后不改变评论来反映改变。