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

我建立的应用程序和要求，一个是使用注释像这样的：为什么我需要在C＃/ .Net代码中使用这些讨厌的注释？

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

我所知，这很容易为各种样的工具来生成基于这些个XML的文档。但它显着降低了代码可读性，这正是我们人类试图实现的目标。

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

来源

2013-08-20 Roman Pushkin

“改善代码可读性和清洁度的更好方法是什么”编写自定义代码而不使用许多注释代码 – wudzik

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

此外，这可以在VisualStudio中折叠 –

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

我认为，文档在保持简短和重点的情况下永远不会是一件坏事，它不会影响代码的可读性。

来源

2013-08-20 07:06:29 npinti

是的，我明白这一点。但同时，很多工具会自动为你粘贴所有这些XML注释（GhostDoc）。在一些公司，他们甚至懒得写更多。他们有这些自动生成的评论是可以的。无论如何，我期待的答案就像是使用工具来隐藏xml注释，或者以更好的方式来组织它们。 –

@RomanPushkin：你可以看看这个链接：http://stackoverflow.com/questions/8696586/c-sharp-hide-and-unhide-comments也许有一些你可能会遇到的信息。 – npinti

XML注释并不是为.NET项目生成文档的唯一方式，而且它们很难看。它们适用于Intellisense或API帮助文件生成，但不包括代码本身的文档，只是暴露的API。像nocco这样的工具解决后一种场景 –

虽然使用第三方DLL确实intellisense会伤害你吗？

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

假设你正在纠正一个dll（或者编写一个别人会使用的类），对他/她来说，当他类型化时，他知道该方法做了什么以及参数是如何工作的对他/她没有帮助吗？

来源

2013-08-20 07:07:45 Ehsan

VS文档和注释不会降低大多数人的代码可读性，反过来也是如此。如果您觉得这些注释使得代码不易读取，您可以折叠它们，甚至改变它们绘制的颜色。

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

来源

2013-08-20 07:09:34

，这正是人们在cshtml之前对aspx的想法 –

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

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

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

但使用起来是一件好事，你习惯了身边有他们

来源

2013-08-20 07:11:57 havardhu

不同的文件格式都适用于不同的场合。

XML注释最适合自动帮助文件生成和智能感知。根据需要，它们比其他方法更详细，因为它们需要特定的标签才能生成文档。虽然语法可能会更好，但是记住，当所有人都认为XML是一个很酷的想法时，它们就会被创造出来。

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

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

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

来源

2013-08-20 07:16:05

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

回答

相关问题