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

Question

我正在开发一款应用程序，其中一个要求是使用像这样的注释：

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

我知道使用各种工具基于这些XML生成文档很容易。但是，这显著降低了代码的可读性，而我们人类正是在追求这一点。

在.Net中，是否可以用其他技术替代这种方法？如何更好地提高代码的可读性和清晰度？

- Roman Pushkin

---

如何提高代码的可读性和简洁性？编写自我解释的代码，尽量不使用过多注释。 - Kamil Budziewski

它以何种方式降低了代码的可读性？它存在于方法本身之外。 - Damien_The_Unbeliever

也可以在VisualStudio中折叠此部分。 - Tobia Zambon

实现清晰且不需要注释的差别与不去记录公共API之间存在很大区别。 - Jon Skeet

@wudzik：但是考虑到这个问题是关于文档的（而不是实现），我不明白你的评论与此有何关联。 - Jon Skeet

Answer 1

当有人使用IntelliSense浏览您的方法时，该信息应该在Visual Studio中弹出。这将节省时间，因为使用您的代码的人不需要进入您的代码（因此也不需要公开您的任何代码）并查看您编写的其他注释。

我认为，文档保持简短并且切题是绝对没有坏处的，它不会影响代码的可读性。

- npinti

---

是的，我明白。但同时，许多工具会自动为您粘贴所有这些xml注释（GhostDoc）。在一些公司中，他们甚至不费心去写更多。对于他们来说，拥有这些自动生成的注释是可以接受的。无论如何，我期望的答案是使用工具隐藏xml注释，或以更好的方式组织它们。 - Roman Pushkin

@RomanPushkin：你可以看一下这个链接：https://dev59.com/aWoy5IYBdhLWcg3wN7e8 或许有你需要的信息。 - npinti

XML注释不是为.NET项目生成文档的唯一方式，而且它们很丑陋。它们适用于Intellisense或API帮助文件生成，但并不涵盖所有场景，例如代码本身的文档，只涉及公开的API。像nocco这样的工具可以解决后者的情况。 - Panagiotis Kanavos

Answer 2

使用第三方dll会影响Intellisense吗？

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

假设您正在编写一个dll（或编写将由其他人使用的类），那么当他输入时，他知道方法的作用以及参数的工作原理，这难道不是有帮助的吗？

- Ehsan

Answer 3

你绝对不应该避免这些注释！它们为Visual Studio提供了智能感知，并且可以成为自动文档工具（如SandCastle）的基础。据我所知，您在技术方面的唯一选择就是使用这种方法（以获得所有这些功能）。

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

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

但是使用它们是一件好事，您会习惯它们的存在。

- havardhu

Answer 4

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

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

对于一般的注释，您可以使用文学编程风格和像nocco这样的工具来创建和显示HTML页面。该工具提取注释并将其与代码一起显示在HTML页面中。 nocco页面本身是nocco.cs上nocco的输出。

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

当然，您可以混合和匹配方法，例如使用XML注释来注释公共方法，使用文学注释来注释内部注释。

- Panagiotis Kanavos

Answer 5

对于大多数人来说，VS文档和注释并不会降低代码的可读性，相反，它们会提高代码的可读性。如果您觉得这些注释使代码变得不太易读，您可以将其折叠或甚至更改它们的颜色。

但是，当您将光标放在函数上方时，方法和参数信息出现时，想象一下这有多么有帮助。这就是最好的可读性。

- No Idea For Name

---

这正是人们在aspx之前所考虑的cshtml。 - Roman Pushkin