评论代码C＃visual studio最佳实践

我正在寻找一个相当武断的答案，所以这可能更多是一个讨论。我想知道在Visual Studio中评论我的C＃代码的最佳做法是什么。现在我使用三重///来生成xml并使用沙堡来构建chm或html文件。但我的问题是，我使用的代码注释的原因有两个：评论代码C＃visual studio最佳实践

当其他开发者使用我的代码，他们可以读取文档，既intellisence和CHM。或html文件。
但我也使用评论作为提醒自己。所以，当我半年后回来时，我可以记住我的想法，以一些复杂的方法。

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

来源

2010-10-29 DNRN

我可以给你最好的建议是：

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

如果方法非常复杂，大部分时间你做错了事（不总是，但总是很接近）。编写易读的代码很难，但是它付出了代价，因为写一篇好的评论，你（或你的大学）一年之后会理解的也很难（甚至可能更难）。清除问题的方法是将方法分解为小方法，并使用非常清晰的变量名称。

一本帮助我创建更好代码的书是Robert Martins Clean Code。如果你还没有阅读，请做。让公司的所有开发人员阅读它。

祝你好运。

来源

2010-10-29 09:50:53 Steven

感谢您的回答。我认为我们都有解决问题的办法，因此我们必须创建好的代码，并且不要用太多的时间来编写代码。有时候评论可以用来作为一个快速和肮脏的修复。而且我知道这不是最佳做法:) – DNRN 2010-10-29 10:00:34

我同意你的意见。质量和经济之间总是存在折衷。我当然写了类似“// TODO：不要忘记重构这个”或“HACK：稍后修复”的评论我自己:-)当然，这取决于项目类型，但我经常发现自己编写的代码已经要维持多年（通常是由我以外的其他人），在这种情况下，如果我在写作时格外小心，它从长远来看确实付出了代价。在编写原型时，我当然不会太在意。 – Steven 2010-10-29 10:16:14

@DNRN：说到经济学，你有没有听说过“技术债务”的概念？这个想法是，如果你在稍后的日期推迟重构，那么你实际上只是获得技术性债务，而这些债务将在未来有利可图的偿还。这种情况的兴趣在于记住代码的作用。相反，我推荐使用ReSharper或CodeRush等质量重构工具，这使得重构工作非常高效。通过使用这样的工具，您可以在两次世界中都能得到最好的结果，而无需额外的时间。 – 2010-10-29 10:25:40

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

使用//注释来评论你的代码，只要代码本身不足以完全理解正在发生的事情。这些评论的观众可能会在未来三个月或另一位开发人员维护您的代码。您可以使用特殊注释，如TODO或BUGBUG来标记您必须重新访问的代码。

来源

2010-10-29 09:50:59

我使用TODO自己作为一个稍后必须实施的事情的小提醒，并且发现它非常有用。我喜欢“范围视图”，其中///用于公开和受保护的API，用于intellisene。在文档文件中用作额外信息的。和/ /只能在稍后查看时才用代码查看。 – DNRN 2010-10-29 10:05:21

我将两种评论风格 - ///作为关于类，方法等的“公共”文档和//关于“私人”评论的自我或跟随我阅读的编码器。

来源

2010-10-29 09:51:38

这也是我所做的。 – Mizipzor 2010-10-29 10:03:35

评论代码C＃visual studio最佳实践

回答

相关问题