为什么我需要在 C#/.Net 代码中使用这些讨厌的注释？ [关闭]答案

【问题标题】：Why do I need to use these nasty comments in C# / .Net code? [closed]为什么我需要在 C#/.Net 代码中使用这些讨厌的注释？ [关闭]
【发布时间】：2026-02-23 12:45:01
【问题描述】：

我正在构建应用程序，其中一项要求是使用这样的 cmets：

/// <summary>
/// Creates new client.
/// </summary>
/// <param name="uri">The URI.</param>
/// <param name="param">The param.</param>
/// <returns></returns>

我了解各种工具很容易根据这些 xml 生成文档。但它显着降低了代码的可读性，而这正是我们人类努力实现的目标。

这种方法可以被 .Net 中的任何其他技术取代吗？提高代码可读性和清洁度的更好方法是什么？

【问题讨论】：

“提高代码可读性和清洁度的更好方法是什么”编写自解释且不使用许多 cmets 的代码
它以什么方式降低了代码的可读性？它存在于方法本身之外。
这也可以在 VisualStudio 中折叠
@wudzik：明确且不需要 cmets 的实现与无需费心记录您的公共 API 之间存在巨大差异。
@wudzik：但鉴于这个问题是关于文档（而不是实施），我看不出你的评论有什么相关性。

标签： c# .net xml-comments

【解决方案1】：

当有人在通过您的方法时使用智能感知时，该信息应该会在 Visual Studio 中弹出。这将节省时间，因为使用您的代码的任何人都不需要进入您的代码（这意味着您也不需要公开任何代码）并查看您编写的其他 cmets。

我认为，当文档保持简短和重点时，绝不是一件坏事，它不会影响代码的可读性。

【讨论】：

是的，当然，我明白这一点。但同时很多工具会自动为您粘贴所有这些 xml cmets (GhostDoc)。在一些公司，他们甚至懒得写更多。他们可以拥有这些自动生成的 cmets。无论如何，我期待答案会像使用一个工具来隐藏 xml cmets，或者以更好的方式组织它们。
@RomanPushkin：你可以看看这个链接：*.com/questions/8696586/…也许有一些你可能想要的信息。
XML cmets 不是为 .NET 项目生成文档的唯一方法，而且它们很丑陋。它们适用于 Intellisense 或 API 帮助文件生成，但并不涵盖所有场景，例如代码本身的文档，只涵盖公开的 API。像 nocco 这样的工具可以解决后一种情况

【解决方案2】：

使用第三方 dll 时，智能感知会伤害您吗？

我认为不会。这是使用此评论的主要原因之一。

假设您正在纠正一个 dll（或编写一个其他人将使用的类），他/她在键入时知道该方法的作用和参数的作用是否对他/她有帮助？

【讨论】：

【解决方案3】：

您绝对不应该避开这些 cmets！它们为 Visual Studio 提供 IntelliSense，并可以形成自动文档工具的基础，例如 SandCastle。据我所知，就技术而言，您唯一的选择是这个（获得所有这些功能）。

为了提高可读性，您可以使用 Visual Studio 中第一个标记旁边的 [-] 来最小化每个注释。这样你只会看到第一行。这在日常处理代码时会很有帮助。

如果您发现 xml 使导航/浏览变得更加困难，我还发现导航下拉列表有助于在类中定位方法。

但是使用它们是一件好事，而且你会习惯有它们在身边

【讨论】：

【解决方案4】：

不同的文档格式适用于不同的场景。

XML cmets 最适合自动生成帮助文件和 Intellisense。必要时，它们比其他方法更冗长，因为它们需要存在特定标签才能生成文档。虽然语法可能会更好，但请记住，它们是在每个人都认为 XML 是一个很酷的想法时创建的。

对于一般性评论，您可以使用像 nocco 这样的文学编程风格和工具来创建和显示 HTML 页面。该工具提取 cmets 并将它们显示在代码旁边的 HTML 页面中。 nocco 页面本身就是 nocco 在 nocco.cs 上的输出

Nocco 甚至使用 Markdown 进行格式化。

当然，您可以混合和匹配方法，例如。将 XML cmets 用于公共方法，将 literate cmets 用于内部 cmets。

【讨论】：

【解决方案5】：

VS 文档和注释不会降低大多数人的代码可读性，反之亦然。如果您觉得这些 cmets 降低了代码的可读性，您可以折叠它们，甚至更改它们绘制的颜色。

但是想想当你把光标放在一个函数上并且方法的信息和它的参数出现时它是多么的有用。这是最好的可读性

【讨论】：

这正是人们在 cshtml 之前对 aspx 的看法