评论代码 C# Visual Studio 最佳实践答案

【问题标题】：commenting code C# visual studio best practice评论代码 C# Visual Studio 最佳实践
【发布时间】：2011-05-02 07:57:09
【问题描述】：

我正在寻找一个相当随意的答案，所以这可能更像是一个讨论。我想知道在 Visual Studio 中评论我的 C# 代码的最佳做法是什么。现在我正在使用三元组 /// 来生成 xml 并使用沙堡来构建 chm 或 html 文件。但我的问题是我使用代码 cmets 有两个原因：

如何在不相互干扰的情况下完成这两个目标，同时又是一项快速的任务，而不是花费大量的编码时间？

【问题讨论】：

【解决方案1】：

我能给你的最好建议是：

不要评论糟糕的代码；重写它！

如果方法非常复杂，则大多数时候您都在做错事（并非总是如此，但几乎总是如此）。编写可读的代码很困难，但它是有回报的，因为编写你（或你的大学）一年后会理解的好的 cmets 也很困难（甚至更难）。让事情变得清晰的方法是将方法分解为更小的命名方法并使用非常清晰的变量名称。

Robert Martins Clean Code 是一本对我编写更好的代码有很大帮助的书。如果您还没有阅读，请阅读。并让贵公司的所有开发人员阅读。

祝你好运。

【讨论】：

感谢您的回答。我认为我们都有为工作获得报酬的决斗问题，因此我们必须创建好的代码并且不要花费太多时间来编写它。有时 cmets 可以用作解决此问题的快速而肮脏的方法。而且我知道这不是最佳做法:)
我同意你的看法。良好的质量和经济性之间总是需要权衡取舍。我当然会自己编写诸如“// TODO：不要忘记重构”或“// HACK：稍后修复”之类的 cmets :-) 当然，这取决于项目的类型，但我经常发现自己编写的代码具有维护多年（通常由我以外的其他人维护），在这种情况下，从长远来看，当我特别小心地编写它时，它确实是值得的。在编写原型时，我当然不会那么在意。
@DNRN：说到经济学，你听说过“技术债”这个概念吗？这个想法是，如果你把重构推迟到以后，你实际上只是获得了未来必须偿还的技术债务，还有利息。在这种情况下，感兴趣的是记住代码所做的事情的开销。相反，我推荐使用质量重构工具，例如 ReSharper 或 CodeRush，它们可以使重构工作变得非常高效。通过使用这样的工具，您可以两全其美……现在就重构，无需额外时间。

【解决方案2】：

使用/// cmets 记录您的公共和受保护的 API。使用<remarks> 描述应如何使用您的 API。这些 cmets 的受众是使用您的代码的其他开发人员。

只要代码本身不足以完全理解正在发生的事情，请使用// cmets 注释您的代码。这些 cmets 的受众可能是未来三个月后的您自己，或者是其他将要维护您的代码的开发人员。您可以使用 TODO 或 BUGBUG 等特殊 cmets 来标记您必须重新访问的代码。

【讨论】：

我自己使用 TODO 来提醒一些以后必须实现的东西，并且发现它非常有用。我喜欢“范围视图”，其中 /// 用于公共和受保护的 API，用于 intellisene。用作文档文件中的额外信息。和 // 仅在以后查看时在代码中查看。

【解决方案3】：

我结合了两种评论风格 - /// 用于类、方法等的“公共”文档，// 用于我自己或跟随我阅读的编码人员的“私有”cmets。

【讨论】：