解决 XML 文档注释困境答案

【问题标题】：Solving the XML doc comment dilemma解决 XML 文档注释困境
【发布时间】：2015-10-18 09:30:38
【问题描述】：

关于 C# 代码中的 XML doc cmets，有两种思想流派：

Robert C. Martin 的“如果您仔细命名您的
类、方法和变量来表达您的工作意图，
你不需要 cmets。”
您需要注释每个公共类、接口、方法和属性

由于程序员很懒惰，许多人使用 GhostDoc 或 Resharper 等工具来自动生成 XML 文档 cmets。这些工具的目的是提供一个基本的注释，程序员可以很容易地对其进行扩展。然而，现实表明，许多生成的 cmets 保持不变。因此，它们在清晰度或可维护性方面没有为代码增加任何价值。未更改的生成的 XML 文档 cmets 只是噪音。在某种程度上，它们是违反 DRY 原则的一种形式。

在我的团队中，我们意识到这些“噪音cmets”的无用之处。但是，我们也不想走所有“根本没有 cmets”的路。一个想法是为所有公共成员生成这样的存根：

/// <summary>
/// TODO
/// </summary>

如果有人签入未触及 TODO cmets 的代码，则构建（我们使用 TFS2013）应该会中断。

我的问题是：

有人做过这样的事吗？怎么样？
还有其他方法可以解决 XML 文档困境吗？
我担心的是，它会减慢需要处理现有未记录代码的团队成员的速度，他们需要进行一些代码考古才能检查即使是很小的更改。有什么想法可以防止这种情况发生吗？

【问题讨论】：

标签： c# coding-style resharper xml-documentation ghostdoc

【解决方案1】：

已经有一个内置的规定，但并不理想：

不要使用评论生成器
不要使用您建议的存根
使用警告级别 = 4 编译
检查 [x] Xml 文档文件
勾选 [x] 将警告视为错误

【讨论】：

我也想过这个选项。缺点是您必须自己将 Xml 文档标题添加到所有公共成员。这就是 Stub 想法产生的原因。
一般的想法是你必须做一些打字。那么触发sn-p的初始///就没有那么麻烦了。