用于C#编程的XML注释技巧

早上好,下午好,晚上好或晚上好(取决于你的时区).

这只是关于C#中XML注释的一般问题.我从来没有对评论我的程序做过很大的贡献,我一直都是一个冗长的变量/属性/方法名称,让代码说明一切.如果我编写的内容相当令人困惑,我会写评论,但在大多数情况下,我不会写很多评论.

我正在阅读有关.NET,Sandcastle和codeplex上的帮助文件构建器中的XML注释的文章,它让我想要记录我的代码并为那些必须深入研究我的人生成一些很好的,有用的文档.代码,当我不在这里.

我的问题是关于标准和惯例.是否有"好"XML评论指南？你应该评论每个变量和属性吗？每个方法？我只是在寻找有关如何编写好的注释的提示,这些注释将由sandcastle编译成良好的文档,以便其他程序员在最终不得不处理我的代码时不会诅咒我的名字.

提前感谢您的意见和建议,Scott Vercuski

就个人而言,我们确保每个公共和受保护的方法都有XML注释.它还将为您提供Intellisense,而不仅仅是最终用户帮助文档.在过去,我们也将它包含在私有范围的声明中,但不要觉得它是100%要求的,只要这些方法很短且很简单.

不要忘记有一些工具可以让您更轻松地进行XML注释任务:

GhostDoc - 注释继承和模板加载项.

Sandcastle帮助文件生成器 - 通过GUI编辑Sandcastle项目,可以从命令行运行(用于构建自动化),并可以编辑MAML以获取不是从代码派生的帮助主题.(1.8.0.0 alpha版本非常稳定且非常好.现在已经使用了大约一个月,超过1.7.0.0)

评论经常过时.这一直是个问题.我的经验法则:更新评论所需的工作越多,评论就越快过时.

XML注释非常适合API开发.它们与Intellisens配合得非常好,可以让您立即生成HTML帮助文档.

但这不是免费的:保持它们会很难(看看任何非平凡的例子,你会明白我的意思),所以它们会很快过时.因此,应将检查XML注释添加到代码审查中作为强制检查,并且每次更新文件时都应执行此检查.

好吧,因为维护成本很高,因为很多非私有符号(在非API开发中)只使用1或2个类,并且因为这些符号通常是不言自明的,所以我永远不会强制执行一条规则说每个非私有符号都应该是XML注释.这将是矫枉过正和具有竞争力的.你会得到的是我在很多地方看到的:几乎空的XML注释没有为symbole名称添加任何内容.而且代码的可读性稍差......

我认为关于普通(非API)代码中的注释的非常非常重要的指导原则不应该是关于它们应该如何编写而是关于它们应该包含什么.很多开发人员仍然不知道该写些什么.应该通过示例对应该注释的内容进行描述,对于您的代码而言,不仅仅是简单的:"在每个非私有符号上使用XML注释."