在 .NET 中使用 XML 注释有哪些优点？
https://stackoverflow.com/questions/2584901
-
24-09-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
Russian题
我无法理解使用 XML 注释的优点。我知道它们可以转换为代码外部的精美文档，但使用更简洁的 DOxygen 语法也可以实现同样的效果。在我看来，XML 注释是错误的，因为：
- 他们总体上混淆了注释和代码。（它们更难被人类阅读）。
- 在单个屏幕上可以查看的代码较少，因为“summary”和“/summary”需要额外的行。
- （已删除）
那么，XML 在 .NET 中比简单的 DOxygen 语法更受青睐的原因可能是什么？
解决方案
在我看来，这里并没有真正正确的答案。实际上，这两个系统都不比另一个系统“更好”——它们最终都完成相同的工作，即允许您生成代码文档。
最终的输出可以以完全相同的方式格式化，并且它们在支持的标签等方面确实具有几乎相同的功能，因此这实际上取决于个人选择。
就我个人而言，我发现 XML 注释更具人类可读性、更符合逻辑并且易于使用 - 但这还有一个额外的优势，即让 Visual Studio 自动生成供我填写的存根，以及它对以下内容的出色支持：折叠它们，这样它们就不会占用屏幕上的大量空间。我确信那些在 VI 或 some_other_IDE 中进行过后台编辑的人会有不同的看法，但是两者都没有真正的优势。
所以我想说，这实际上取决于您使用的 IDE 以及您和您的团队习惯使用的 IDE。
现在，如果您问为什么 Microsoft 选择在 Visual Studio 中与 XML 注释如此紧密地集成，那是另一个问题了。最有可能的原因是：他们在 VS 中实现会更简单（因为他们可以重用现有代码来生成/读取注释并构建智能感知等），无论如何他们都有坚持“标准”的趋势（无论是他们自己的标准还是行业标准） ），以及杰夫提到的许可原因。
补充一下，微软在 VS 中使用的产品称为“Sandcastle”，它是一个内部 XML 文档生成工具。它有自己的维基页面@ http://docproject.codeplex.com/Wikipage
其他提示
- 使用该方法时，IDE 会拾取注释并显示它们。
- 每个编写 C# 程序的人可能都熟悉 XML 注释系统。对于新员工来说，需要学习的东西更少。
我并不是说 DOxygen 更好，只是 xml 注释系统大家更熟悉，而且还有很长的路要走。这只是少了一件你必须培训新员工要做的事情。
至于不注释变量。对您来说可能显而易见的事情对其他人（或 6 个月后的您）来说可能并不明显。
好吧，现在我想我明白你在问什么了。
混淆评论。颜色编码有帮助。就我个人而言，我会快速浏览灰色文本，只阅读绿色文本，除非我需要阅读 xml 文本。（至少在我的设置中）。
我们有大显示器，因此我们通常会在屏幕上看到更多代码。（购买大型显示器通常比重新培训人员更便宜）。关于这一点的另一件事是，我敢打赌，您一次只会主动查看一个函数，因此，如果整个函数适合一个页面，您可能不会因为看不到更多代码而受到太大影响。现在，如果函数很长，那么我可以看到这是一个问题。
如果可能的话，我们将摘要注释放在一行上（假设它不是很大）。这减少了已用空间。
我不知道 DOxygen 是否会这样做，但您可以折叠注释，这样它们就不会妨碍您。
XML 文档的主要工作是 不是 生成文档。它是为您班级的客户提供良好的 IntelliSense 信息。将生成的 .xml 文件与程序集一起发送。
在 .NET 中使用 XML 注释的优点
它们本身受 C# 编译器和 Visual Studio 支持，提供一个位置来记录 API，以便在打印、在线和智能感知文档中使用。
本文来自MSDN杂志 陈述如下：
在每个项目中，都有一个对文档不满意的人。团队领导需要更多的评论，技术作家希望更多有关代码设计，质量保证希望看到功能规范等的书面信息。如果实际写所有这些文件，那么您仍然需要将所有文件保持同步。
虽然格式不一定是理想的，但 XML 文档注释提供了丰富的语法，因此可以实现这一点。
为什么不在 C# 中支持 DOxygen？
至于为什么选择现有的 XML 系统而不是 DOxygen，我怀疑这主要是因为 氧气 是根据 通用公共许可证 这意味着 Visual Studio 和 C# 编译器也需要同样发布 - 考虑到 Microsoft 无疑不会愿意这样做 GPL 条款.
你不 有 在您的项目中使用它们。
他们是 A 标准恰好集成到 Visual Studio 中，如果您使用 StyleCop，则可以强制执行它们。所以这就是这里的美德。
然而，如果您决定使用 DOxygen，那么没有什么可以阻止您。只要确保你的行为保持一致即可。
