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

Question

我无法理解使用XML注释的优点.我知道它们可以转换成代码外部的漂亮文档,但使用更简洁的DOxygen语法可以实现相同的目标.在我看来,XML注释是错误的,因为:

1. 它们总体上混淆了评论和代码.(它们更难以被人类阅读).
2. 可以在单个屏幕上查看更少的代码,因为"summary"和"/ summary"需要额外的行.
3. (已删除)

那可能是什么原因,为什么XML在.NET中更受欢迎而不是简单的DOxygen语法？

Answer 1

1. ide使用该方法获取注释并显示它们.
2. 编程C#的每个人都可能熟悉XML注释系统.新员工的学习成果较少.

我并不是说DOxygen不是更好,只是xml评论系统对每个人来说都比较熟悉,而且还有很长的路要走.你只需要培训新员工就可以了.

至于将变量取消注释.对你来说可能是显而易见的,不会对其他人(或6个月后的你).

好了,我想我明白了你在问什么.

1. 混淆评论.颜色编码有帮助.就个人而言,我快速扫描灰色文本,只读取绿色,除非我需要阅读xml文本.(至少在我的设置中).

2. 我们有大型显示器,所以我们通常会在屏幕上获得更多代码.(购买大型显示器比购买大型显示器更便宜).关于这一点的另一件事是,我打赌你一次只是主动查看一个函数,所以如果整个函数适合页面,你可能不会因为没有看到更多代码而遭受太多痛苦.现在,如果函数很长,那么我可以看出这是一个问题.

3. 我们在可能的情况下将摘要注释放在一行(假设它不是很大).这减少了用过的空间.

4. 我不知道DOxygen是否这样做,但你可以删除评论,这样它们就可以了.

Answer 2

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

Answer 3

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

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

就我个人而言，我发现 XML 注释更具人类可读性、更符合逻辑并且易于使用 - 但这还有一个额外的优势，即让 Visual Studio 自动生成供我填写的存根，以及它对以下内容的出色支持：折叠它们，这样它们就不会占用屏幕上的大量空间。我确信那些在 VI 或 some_other_IDE 中进行过后台编辑的人会有不同的看法，但是两者都没有真正的优势。

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

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

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