logo标签列表

在.NET中使用XML注释的优点是什么？

c#doxygenxml-comments
9
我不理解使用XML注释的优点。我知道它们可以被转换成漂亮的文档，但是更简洁的DOxygen语法也可以实现相同的效果。在我看来，XML注释是错误的，因为：
  1. 它们使评论和代码晦涩难懂（对人类来说更难读）。
  2. 单个屏幕上可以查看的代码更少，因为“summary”和“/summary”需要额外的行。
  3. （已删除）
那么为什么.NET更喜欢使用XML而不是简单的DOxygen语法呢？
1
XML标准定义了如何进行注释。我们对此没有发言权。它们的“好坏”是无关紧要的，因为它就是这样。 - skaffman
嗯，等一下，你是在指的使用XML的特定技术，而不是一般的XML吗？ - skaffman
3
@skaffman - 我认为他的意思是C#中的XML文档注释。 - Oded
@Michal：所以，您的意思是C＃中的XML注释吗？ - KMån
我提出这个问题是考虑到C# XML注释。 - Michal Czardybon
2
#3 是完全误导性的。Doxygen 还强烈建议您记录每个参数，并在您不这样做时生成警告。 - Ben Voigt
6个回答
10
  1. 当使用该方法时，IDE会接收并展示注释。
  2. 所有编写C#代码的人都可能熟悉XML注释系统。对于新员工来说，需要学习的东西更少。

我并不是说DOxygen不好，只是XML注释系统更为常见，这样更方便大家。这就是你无需培训新员工做的一件少事。

至于留下未加注释的变量。对于你来说很明显的内容对别人（或者过了6个月再看的你）来说未必如此。

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

  1. 混淆的注释。颜色编码有所帮助。个人而言，我会快速浏览灰色文本，并且只读取绿色文本（至少在我的设置中）。

  2. 我们有大屏幕，因此通常可以在屏幕上显示更多的代码。（购买一个大屏幕比重新培训人员成本更低）。另外一个方面也是，我打赌你通常只会同时关注一个函数，所以如果整个函数可以放在一页上，那么你可能不太需要看到更多的代码。现在如果函数很长，那么我可以看到这可能是个问题。

  3. 我们尽可能将摘要注释放在一行上（假设没有太大）。这样可以节省使用空间。

  4. 我不知道DOxygen是否支持此功能，但你可以折叠注释以使其脱离视线。

(1) IDE也可以被制作成能够捕捉到类似DOxygen格式的注释。 (2) 我在询问两种注释方法的技术比较，而不是相关业务决策的比较。因此，我认为这两点都离题了。 - Michal Czardybon
2
我完全看不懂你在问什么。注释与代码的运行方式无关，这纯粹是关于如何向其他程序员和自己传达代码要做什么的商业决策。 - kemiller2002
2
我喜欢你的回答，Kevin，但我不同意你的评估：“这纯粹是业务决策”。尽管经理更可能选择具有更多缩放损失（熟悉）而不是具有更多开销（新事物）的路径，但在我看来，这是一个糟糕的商业选择。无论如何，对我来说很清楚，Michal正在寻找诸如：哪个选项将帮助我比另一个更好地进行沟通？或哪一个将帮助我比另一个更好地完成工作？的技术原因。 - Joseph Gordon
我想这就是我的瓶颈所在。对我而言，那些是商业决策而非技术决策。对我而言，技术决策是指我们使用X，因为它可以在这种情况下增加吞吐量。 我并不完全不同意你的看法，仅仅基于熟悉度来选择一个而不是另一个可能是一个糟糕的商业选择，但你必须权衡利弊。很多人可能并没有看到从一种东西转换到另一种东西的优势，改变会有很多开销，有时候，与去使用更好的东西相比，还好已经足够了。 - kemiller2002
8
XML文档的主要作用不是生成文档，而是为您类的客户端提供良好的IntelliSense信息。请随程序集一起发布生成的.xml文件。
我不同意智能感知信息不是文档的说法，但提到它是一个有效的观点。我认为如果没有智能感知，我会迷失方向。 - Tom W
4

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

C#编译器和Visual Studio原生支持XML注释，提供了一个单一的位置来记录API，这些API可以用于打印、在线和智能感知文档。

MSDN杂志上的这篇文章指出：

在每个项目中，总有人对文档不满意。团队领导希望在源代码中增加更多注释，技术作家希望在代码设计方面增加更多书面信息，质量保证人员希望看到功能规格说明等等。如果所有这些文档都实际编写了，你仍然需要努力保持它们的同步。

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

为什么不支持C#中的DOxygen？

至于为什么选择现有的XML系统而不是DOxygen，我认为这主要是因为DOxygen是根据GPL发布的，这意味着Visual Studio和C#编译器也需要按照GPL发布 - 这是微软无论如何都不想做的事情，考虑到GPL的条款和条件。

3
我发现更让人惊讶的是GhostDoc插件的普及度。如果可以根据方法名自动生成注释，为什么还需要注释呢？Steve Yegge表示，过度注释是新手程序员的标志，我很难不同意他的看法。
1
这不是关于过度注释的问题 - 而是关于特定使用XML注释的问题，这些注释主要用于明确记录代码。如果您依赖方法名称，则不包括语义，这意味着未来维护可能会改变方法的含义并使文档中的含义无效。通过XML注释对方法进行注释有助于避免这种情况，同时还提供了用于智能感知和其他地方的文档。 - Jeff Yates
@Jeff Yates：我强烈反对。如果你改变了意思，那么你必须同时改变名称。正确的方法名称比注释更重要。 - Michal Czardybon
@Matt：即使可以自动生成，但注释仍然存在是因为智能感知。在使用方法时显示一些文档可以提供信心，表明您正在正确使用它。如果没有它，您就在猜测，尽管您可能猜对了，但您无法确定您是否正确地解释了作者的意图。智能感知（和其他API文档）有助于解决这个问题，XML注释有助于生成此类文档。 - Jeff Yates
@Jeff：例如，如果我有一个方法“UpdateName(string newName)”，在注释摘要中写上“更新名称”会如何帮助任何人理解正在发生的事情？它只是增加了3行噪音。我并不是说永远不需要注释，我想说的是，只有当开发人员未能想出适当描述性名称时，才应该存在注释。如果它们没有添加任何内容，它们就不应该存在。 - Matt Briggs
@Matt：当然，不良评论是噪音。这没有任何借口，但只因为评论可以自动生成，并不意味着它就是噪音。评论必须提供适当的细节。如果你只使用ghostdoc创建最基本的注释，那么你就没有做好工作。 - Jeff Yates
显示剩余3条评论
1

你并不是必须在你的项目中使用它们。

它们是一个标准，恰好集成在Visual Studio中，如果你使用StyleCop，它们可以被强制执行。所以这就是这里的优点。

然而，如果你决定要使用DOxygen，那么没有什么可以阻止你。只要确保你是一致的。

1

在我看来，这里并没有一个正确的答案。实际上，两个系统都能完成同样的工作，即允许您生成代码文档，因此它们在本质上都没有“更好”的一方。

最终输出可以以完全相同的方式格式化，它们在支持标签等方面几乎具有相同的功能，因此这真的取决于个人选择。

就个人而言，我发现XML注释更易于阅读，更合乎逻辑，而且使用起来非常简单 - 但这是在Visual Studio自动为我生成存根的优势下，并且它对折叠注释的支持非常出色，因此它们不会占用屏幕上的大量空间。我相信，来自VI或其他IDE背景的编辑者会有不同的意见，但是两者之间没有真正的优势。

因此，我认为这取决于您使用的IDE以及您和您的团队习惯使用什么。

如果你问为什么微软选择在Visual Studio中与XML注释紧密集成，那就是另外一个问题了。很可能是因为：它对他们来说更容易在VS中实现（因为他们可以重用现有的代码来生成/读取注释并构建智能感知等），无论是自己的标准还是行业标准，他们都有坚持“标准”的趋势，并且正如Jeff所提到的那样，还有许可证原因。

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

+1 关于IDE功能的评论。我实际上会在Visual Studio中关闭所有折叠功能，并且通常更喜欢纯文本代码的方法。这可能是另一个问题的话题。 - Michal Czardybon
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接