9

我无法理解使用 XML 注释的优点。我知道它们可以转换为代码外部的漂亮文档，但同样可以使用更简洁的 DOxygen 语法来实现。我认为 XML 注释是错误的，因为：

  1. 它们通常混淆了注释和代码。（它们更难被人类阅读）。
  2. 可以在单个屏幕上查看更少的代码，因为“summary”和“/summary”需要额外的行。
  3. （已删除）

那么可能是什么原因，为什么在 .NET 中首选 XML 而不是简单的 DOxygen 语法？

4

6 回答 6

10
  1. ide 会在使用该方法时提取注释并显示它们。
  2. 编写 C# 的每个人都可能熟悉 XML 注释系统。新员工需要学习的东西更少。

我并不是说 DOxygen 不好，只是 xml 评论系统大家比较熟悉，而且还有很长的路要走。这只是您培训新员工要做的一件事。

至于不注释变量。对您来说可能很明显的事情，对其他人（或 6 个月后的您）来说不会是显而易见的。

好的，现在我想我明白你在问什么了。

  1. 混淆评论。颜色编码有帮助。就个人而言，除非我需要阅读 xml 文本，否则我会快速浏览灰色文本并只阅读绿色文本。（至少在我的设置中）。

  2. 我们有大型显示器，因此我们通常会在屏幕上获得更多代码。（购买大型显示器比一般重新培训人员便宜）。关于这一点的另一件事是，我敢打赌你一次只积极地查看一个函数，所以如果整个函数适合一个页面，你可能不会因为看不到更多代码而遭受太多痛苦。现在，如果函数很长，那么我可以看到这是一个问题。

  3. 我们尽可能将摘要注释放在一行（假设它不是很大）。这减少了已用空间。

  4. 我不知道 DOxygen 是否这样做，但您可以折叠评论，以便它们不碍事。

于 2010-04-06T13:00:54.710 回答
7

XML 文档的主要工作不是生成文档。它是为您班级的客户提供良好的 IntelliSense 信息。将生成的 .xml 文件与您的程序集一起发送。

于 2010-04-06T13:14:56.247 回答
4

在 .NET 中使用 XML 注释的优点

它们受到 C# 编译器和 Visual Studio 的原生支持，提供了一个单一位置来记录您的 API，以便在印刷、在线和智能感知文档中使用。

这篇来自 MSDN 杂志的文章指出：

在每个项目中，都会有人对文档不满意。团队负责人希望在源代码中获得更多评论，技术编写人员希望获得有关代码设计的更多书面信息，质量保证希望查看功能规范等等。如果所有这些文档都是实际编写的，那么您仍然需要保持所有文档同步。

虽然格式不一定是理想的，但 XML 文档注释提供了丰富的语法，因此可以实现这一点。

为什么不在 C# 中支持 DOxygen 呢？

至于为什么选择现有的 XML 系统而不是 DOxygen，我怀疑这主要是因为DOxygen是在GPL下发布的，这意味着 Visual Studio 和 C# 编译器也需要这样发布——微软无疑不会这样做想做考虑GPL 的条款。

于 2010-04-06T13:17:39.243 回答
3

我发现更令人震惊的是ghostdoc插件的流行。如果可以根据方法名称自动生成注释，那为什么还要注释呢？

Steve Yegge 说过度评论是新手程序员的标志，我很难不同意他的观点。

于 2010-04-06T13:01:18.080 回答
1

您不必在项目中使用它们。

它们是恰好集成到 Visual Studio中的标准，如果您使用 StyleCop，它们可以强制执行。所以这就是这里的美德。

但是，如果您决定要使用 DOxygen，那么没有什么能阻止您。只要确保你是一致的。

于 2010-04-06T13:01:31.117 回答
1

imo这里没有真正正确的答案。实际上，这两个系统都不比另一个“更好”——它们最终都做同样的工作，即允许您生成代码文档。

最终输出可以以完全相同的方式对它们中的每一个进行格式化，并且它们在所支持的标签等方面确实具有几乎相同的功能，所以这真的取决于个人选择。

就我个人而言，我发现 XML 注释更易于阅读、更合乎逻辑且易于使用 - 但这具有让 Visual Studio 自动生成存根供我填写的额外优势，以及它对折叠它们，这样它们就不会占用屏幕上的大量空间。我敢肯定，在 VI 或 some_other_IDE 中进行后台编辑的人会有不同的看法，但两者都没有真正的优势。

所以我想说，这实际上取决于您使用的是什么 IDE，以及您和您的团队习惯使用什么。

现在，如果您要问为什么 Microsoft 选择在 Visual Studio 中如此紧密地集成 XML 注释，这是一个不同的问题。很可能是由于以下事实：他们在 VS 中实现会更简单（因为他们可以重用现有代码来生成/读取评论并构建智能感知等），他们有坚持“标准”的趋势“无论如何（无论是他们自己的还是行业的），以及杰夫提到的许可原因。

只是补充一点，微软在 VS 中使用的产品称为“Sandcastle”，它是一种内部 XML 文档生成工具。它有自己的 wiki 页面 @ http://docproject.codeplex.com/Wikipage

于 2010-04-06T14:43:36.217 回答