您认为最好的C＃评论结构是什么？特别是使用Visual Studio

Question

多年来，我经历过学校并一直在这个行业工作，我经常向人们征求意见建议。遗憾的是，众所周知，与许多开发人员进行评论是一个侧面说明，而不是其他内容。话虽如此，我通常得到一个相当一般的答案。真的，这对于了解随着时间的推移真正有用的东西并没有多大帮助。

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

Answer 1

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

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

Answer 2

我在撰写评论时会尝试遵循一些基本准则。

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

Answer 3

“很多而且经常” --Bilbo，The Hobbit。

更严重的是，评论一些不明显的事情，并告诉读者代码的目标是什么，以及为什么选择它。

根据语言，这不会改变。

Answer 4

我个人使用三重斜杠，SandCastle XML注释和内联注释的组合来处理更复杂的部分。经常评论，但要保持简洁，没有人需要阅读大量的绒毛，然后才能弄清楚是什么： - ）