你认为最好的 C# 注释结构是什么？特别是使用 Visual Studio答案

【问题标题】：What do you think is the best C# Commenting Structure? Specifically with Visual Studio你认为最好的 C# 注释结构是什么？特别是使用 Visual Studio
【发布时间】：2010-09-16 08:09:40
【问题描述】：

多年来，当我完成学业并在该行业工作时，我经常向人们征求有关评论的建议。可悲的是，众所周知，与许多开发人员发表评论只是一个旁注，而不是其他什么。话虽如此，我通常会得到一个相当笼统的答案。确实，随着时间的推移，这对看看真正有帮助的东西没有多大帮助。

那么，您认为用 Visual Studio 构建 C# 的最佳方式是什么？

【问题讨论】：

很高兴知道为什么有人反对这篇文章。

标签： c# visual-studio comments

【解决方案1】：

至少，我会使用triple-slash XML comment block 评论您的公共 API 的所有部分。如果时机成熟，这将使自动生成文档变得容易。

除此之外，我会评论任何在六个月内将难以破译的特定算法或代码片段。这种“自私”的评论方式（即假设您以后必须维护此代码）通常会在不过度杀伤的情况下实现充足文档的最佳平衡。

【讨论】：

【解决方案2】：

我在编写 cmets 时尝试遵循一些基本准则。

评论应该简单
评论应该清晰
在编写实现之前编写文档
记录为什么你在做某事，而不是做什么你在做什么。
对接口、方法、属性和类使用内置（XML 样式）cmets。
在每个文件（例如，Something.cs）的顶部提供摘要，包括文件名、描述、开发历史和版权信息
为错误修复添加 cmets（如果适用，请提供错误编号）
利用有用的注释，例如 //TODO //BUG 和 //BUGFIX
除非您打算使用，否则不要注释掉代码
将 cmets 添加到它们适用的代码行上方，而不是行尾
尝试将 cmets 限制为单行
使用 // 而不是 /* */ 用于多行 cmets
要清楚——不要使用“foo”、“bar”等。
在适当的情况下遵循大小写规则（例如，camelCasing 和 PascalCasing）

【讨论】：

【解决方案3】：

“很多而且经常” ——比尔博，霍比特人。

更严肃的，评论不明显的东西，并告诉读者代码的目标是什么，也许你选择它的原因。

这不会因语言而改变。

【讨论】：

【解决方案4】：

对于更复杂的部分，我个人使用三斜杠、SandCastle XML cmets 和内联 cmets 的组合。经常评论但保持简洁，没有人需要阅读大量的绒毛才能弄清楚某些东西的作用:-)

【讨论】：