1

关于 C# 代码中的 XML 文档注释，有两种思想流派：

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

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

在我的团队中，我们意识到这些“噪音评论”是无用的。但是，我们也不想采取所有“完全不发表评论”的方式。一个想法是为所有公共成员生成这样的存根：

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

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

我的问题是：

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

1 回答 1

1

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

  • 不要使用评论生成器
  • 不要使用您建议的存根
  • 编译时警告级别 = 4
  • 检查 [x] Xml 文档文件
  • 检查 [x] 将警告视为错误
于 2015-10-18T10:39:11.033 回答