你怎么喜欢你的意见？[关闭]

StackOverflow https://stackoverflow.com/questions/121945

  •  02-07-2019
  •  | 
  •  

题

什么是你最好的做法发表意见？当他们应该被用，以及他们应当包含?或者是评论意见甚至是必要的？

有帮助吗？

解决方案

评论对于可维护性至关重要。最重要的一点是要解释为什么你在做什么，而不是 WHAT 。

其他提示

在学校，规则是评论所有内容，以至于评论超过了代码。我认为这很愚蠢。

我认为应该使用评论来记录“为什么”。代码背后，而不是“如何”......代码本身解释了“如何”。如果有一项操作不清楚为什么要这样做，那么这是一个评论的好地方。

TODO和FIXME有时会发表评论，但理想情况下，他们应该使用您的源代码管理和错误跟踪工具。

我不介意看似无用的注释的一个例外是文档生成器，它只会打印被注释函数的文档 - 在这种情况下，每个公共类和API接口都需要至少评论到获取生成的文档。

理想情况下，您的程序可以在代码中与读者进行通信，而不是在评论中进行。在我看来，编写其他程序员可以快速理解的软件的能力将最好的程序员与平均程序员区分开来。通常，如果您或您的同事无法理解没有评论的代码部分，那么这就是“代码味道”。和重构应该是有序的。但是，有一些古老的库或其他集成，一些评论指导普通开发人员不一定是坏的。

作为经常的回答是：它依赖。我认为你写了一个评论是非常重要的决定，如果评论是好还是坏。有很多可能的原因的评论：

  • 为使结构更清晰的(即其中的循环在这里结束)

坏： 这看起来像一个可能的码的气味。为什么代码那么复杂，它需要一个注释清楚了吗？

  • 解释什么代码

非常糟糕： 这是在我看来危险。通常会发生，即你后改变代码，而忘记了评论。现在的意见是错误的。这是非常糟糕的。

  • 来表示一个解决方法/一修正

好的： 有时候解决问题的办法似乎很清楚，但简单的方法有一个问题。如果你解决问题，它可能有助于增加一个注释，为什么这种方法选择。否则另一个程序后，可以认为，他"优化"的代码和重的错误。认为关于Debian OpenSSL-问题。Debian开发者除去一个未初始化的变量。通常一个未初始化的变量是一个问题，在这种情况下，它需要随机性。一个代码注释将有助于清楚了。

  • 对于文件的目的

好的： 一些文件可以产生的特殊格式的评论(即如果是的话，为什么不试).它是有帮助的文件公共Api，这是一个必须具备的。重要的是要记住，文件中包含的打算代码，不实施。所以答案的评论的问题为什么你需要的方法(和如何使用它)'或什么方法？

我认为删除评论的新动作很糟糕......原因是，有很多程序员认为他们编写的代码很容易理解不需要评论的代码。但实际情况并非如此。

你阅读并立即理解其他人的代码有多大百分比..也许我读过太多经典的asp，Perl和C ++，但我阅读的大部分内容都很难撇去。

你有没有读过某人的代码，并对它完全感到困惑。你觉得他们在写作的时候想过，这是垃圾，但我并不在乎。他们可能认为哦......这非常聪明，而且 SUPER 很快。

只是一些评论：

评论对于从代码中无法轻易推断的所有内容都很重要（例如复杂的数学算法）。

评论的问题是，它们需要像代码一样进行维护，但通常根本不进行维护。

我不喜欢这样的评论：

// 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 );
}

现在代码讲述了整个故事。无需发表评论。

我认为这取决于情景。

方法/函数/类需要简要描述它们的作用，它们是如何做的，它们采取什么以及它们返回的内容，如果不是立即显而易见的，并且通常（在我的代码中）以javadoc的形式出现 - 风格评论块。

在块代码中，我倾向于在一行代码上面留下注释来解释它的作用，或者如果它是一个简短而神秘的函数调用则在行尾添加一个注释。

使用标签搜索，您会发现SO已经有很多关于代码注释的讨论：

https://stackoverflow.com/questions/tagged/comments

评论代码

查看代码完成。它最适合这些主题。

许可以下： CC-BY-SA 和 归因
不隶属于 StackOverflow
scroll top