您对评论的最佳做法是什么？什么时候应该使用它们，它们应该包含什么？或者甚至需要评论？
Brian
问问题
8877 次
9 回答
62
注释对于可维护性至关重要。要记住的最重要的一点是解释你为什么做某事，而不是你在做什么。
于 2008-09-23T16:01:21.267 回答
10
在学校里，规则是评论一切，以至于评论超过了代码。我认为这很愚蠢。
我认为注释应该用来记录代码背后的“为什么”，而不是“如何”……代码本身解释了“如何”。如果有一个操作并不清楚为什么要完成，这是一个发表评论的好地方。
TODO 和 FIXME 有时会出现在注释中，但理想情况下它们应该出现在您的源代码管理和错误跟踪工具中。
我不介意看似无用的注释的一个例外是文档生成器，它只会打印已注释函数的文档 - 在这种情况下，每个公共类和 API 接口都需要至少得到足够的注释才能获得文档生成。
于 2008-09-23T16:03:54.660 回答
8
答案通常是：视情况而定。我认为您写评论的原因对于决定是好是坏非常重要。评论有多种可能的原因：
- 使结构更清晰（即哪个循环在这里结束）
不好：这看起来像是一种可能的代码异味。为什么代码如此复杂，以至于需要注释来清除它？
- 解释一下代码的作用
非常糟糕：我认为这很危险。通常会发生，您稍后更改代码并忘记注释。现在评论是错误的。这真是太糟了。
- 表示解决方法/错误修复
好：有时一个问题的解决方案看起来很清楚，但简单的方法有问题。如果您解决了问题，添加评论可能会有所帮助，说明选择此方法的原因。否则，稍后的另一个程序员可能会认为，他“优化”了代码并重新引入了错误。想想 Debian OpenSSL 问题。Debian 开发人员删除了一个未初始化的变量。通常一个统一变量是一个问题，在这种情况下它是随机性所需要的。代码注释将有助于清除这一点。
- 用于文档目的
好：可以从特殊格式的注释（即 Javadoc）生成一些文档。记录公共 API 很有帮助，这是必不可少的。重要的是要记住，文档包含代码的意图，而不是实现。所以回答评论“为什么需要该方法（以及如何使用它）”或该方法是什么？
于 2008-09-23T16:10:25.707 回答
7
理想情况下，您的程序可以通过代码而不是注释与读者交流。在我看来，编写其他程序员可以快速理解的软件的能力将最好的程序员与平均水平区分开来。通常，如果您或您的同事无法理解一段没有注释的代码，那么这是一种“代码异味”，应该按顺序进行重构。但是，会有一些过时的库或其他集成，一些评论来指导普通开发人员并不一定是坏事。
于 2008-09-23T16:07:35.447 回答
2
我认为删除注释的新运动很糟糕……原因是，有很多程序员认为他们正在编写易于理解的不需要注释的代码。但实际上并非如此。
你阅读了多少其他人的代码并立即理解它。也许我阅读了太多经典的 asp、Perl 和 C++，但我阅读的大多数内容都很难略读。
你有没有读过某人的代码，并被它完全弄糊涂了。你认为他们在写作时会想，这是废话，但我并不在乎。他们可能认为哦……这非常聪明，而且速度会非常快。
于 2008-09-24T20:09:52.767 回答
2
只是一些注释：
注释对于不能从代码中轻易推断出的所有内容（例如复杂的数学算法）都很重要。
注释的问题在于，它们需要像代码一样维护，但通常根本不维护。
我不喜欢这样的评论：
// Create the "Analyze" button
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );
更好的：
CreateAnalyzeButton();
void CreateAnalyzeButton()
{
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );
}
现在代码讲述了整个故事。无需评论。
于 2010-02-19T19:27:15.883 回答
1
我认为这取决于场景。
方法/函数/类需要简短描述它们的作用、它们是如何做的、它们采用什么以及它们返回什么，如果不是很明显并且通常（在我的代码中）以 javadoc 样式的注释块的形式出现.
块内代码，我倾向于在一行块上方留下注释来解释它的作用，或者如果它是一个简短而神秘的函数调用，则在行尾留下注释。
于 2008-09-23T16:02:00.360 回答
0
于 2008-09-23T16:04:49.557 回答
0
看看代码完成。它最适合此类主题。
于 2009-11-02T05:16:25.437 回答