5

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

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

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

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

4

5 回答 5

7

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

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

于 2013-08-20T07:06:29.803 回答
2

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

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

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

于 2013-08-20T07:07:45.323 回答
1

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

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

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

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

于 2013-08-20T07:11:57.253 回答
1

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

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

对于一般评论，您可以使用有文化的编程风格和工具（如nocco）来创建和显示 HTML 页面。该工具提取注释并将它们显示在代码旁边的 HTML 页面中。nocco 页面本身是 nocco 在 nocco.cs 上的输出

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

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

于 2013-08-20T07:16:05.373 回答
0

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

但是想想当您将光标放在函数上方并且方法及其参数的信息出现时它是多么有帮助。这是最好的可读性

于 2013-08-20T07:09:34.843 回答