PHP我应该写评论/文档

Question

一旦我在“清洁代码”书中读到不应该写的评论，因为他们搞砸了代码。

然而，“kohana”代码（作为众多代码之一）在几乎每一行代码之前都包含大量文档和注释。

我正在创建将在未来由用户程序员使用的项目......我该如何写评论呢？

为了使这更清楚 - 我应该：

每次上课之前

• 写文档？
• 在每种方法之前写文档？
• 写@param，@return ...对于每种方法？
• 为几乎每一行代码写评论，使其更清晰？

Answer 1

您应该：每个类的每个方法

写@参数之前

写文档之前

• 写文档，@返回......每个公共方法

对每一行代码的评论都不是太必要，但我建议他们使用其他方式不清楚或模糊的代码。

Answer 2

我写的两个重大案件的意见/文档：

• 当一些节目确实不是立即明显。即使它现在看起来很明显，也不会在6个月内，或者到另一个试图维持你的工作的人。
• 当变量/参数/属性类型不清晰。那时候我添加了一个docblock。

大多数（所有）体面的IDE都具有折叠甚至隐藏评论的机制。不要放弃它们，因为一本书告诉了你，或者因为你认为它是“杂乱”。

凌乱是一个主观的术语。我认为写一条评论线可以为未来你节省10个小时的头痛。

Answer 3

说实话，我会考虑未来的读者。他们会从评论中受益吗？就我自己而言，我只对我没有写的评论感到遗憾，很少对我所做的不必要的评论感到遗憾。很多时候我都以为“没有办法，我会忘记这个”......并且确实如此。

作为一种替代方案，您还可以使用完整评论维护代码的单独副本，以及删除大部分/所有评论的发布版本。

Answer 4

无论你读过哪本书说的评论都不应该写出来，你应该马上扔掉，永远忘记。我不在乎你是否是唯一一个会使用代码的人，你仍然应该记录它。对于我来说，如果您正在处理其他开发人员将使用的代码，我会尝试使用PHPDoc（JavaDoc）样式的文档，这意味着您将每个类，方法，属性等文档记录为尽可能彻底。这带来的一个好处是，许多IDE将实际使用这些信息来完成代码，使您的应用程序更易于使用。

现在在代码块中，我不认为你需要评论每一行（尤其是那些很容易显示你在做什么的行），但是注释代码的不同部分，不同的逻辑分支等

另外一个非注释的事情，我也建议，是使用变量名称是有意义的（除了简单的计数器）。通常情况下，人们会变得可爱并且想要使用3-4个字母的变量名称，因为一些错误的观点认为它会在输入时使用相同的时间，或者缩短它们的代码。如果你需要一个像product_catalog_iterator这样的长名来形容一门课，那对我来说比prodcatit或类似的要好。

Answer 5

我是一个不写评论的人。而是编写自我评论的代码。我的意思是你的功能和变量描述他们的工作。例如，你可以把它写两种方式：

function foo1($a, $b, $c){ 
return md5($a . $b . $c); 
} 

，或者你可以写

function encryption($pepper, $content, $salt){ 
return md5($pepper . $content . $salt); 
} 

在这个例子中，你不知道它在做什么的第一个，但第二次，一个你确切地知道它在做。我唯一需要感觉评论的就是在你编写非常难看的代码之后，你需要很长时间才能弄清楚如何去做，而不是很清楚它在做什么。然而，这应该是远在两者之间。

文档不是一个好主意的原因，是因为通常发生的事情是，您在函数首次创建时，然后在错误修复和维护之后编写出色的评论。评论从未更新过，现在评论说这个功能没有做的事情，并提供了困惑，而不是帮助。