0

一旦我在“清洁代码”一书中读到不应该写注释，因为它们会弄乱代码。

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

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

为了更清楚地说明这一点 - 我应该：

  • 在每节课之前写文档？
  • 在每个方法之前写文档？
  • 为每个方法写@param，@return...？
  • 为几乎每一行代码编写注释以使其更清晰？
4

5 回答 5

3

你应该：

  • 每节课前写文档
  • 在每个方法之前编写文档
  • 为每个公共方法编写@param、@return...

对每一行代码的注释不是太必要，但我建议在代码行中添加注释，否则这些代码会不清楚或晦涩难懂。

于 2012-11-27T20:40:19.387 回答
1

我在两种主要情况下写评论/文档：

  • 当程序所做的事情不是很明显时。即使现在看起来很明显，也不会在 6 个月内出现，也不会出现在另一个试图维持你工作的人身上。
  • 当变量/参数/属性类型不明确时。那是我添加文档块的时候。

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

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

于 2012-11-27T20:40:25.657 回答
1

老实说，我会考虑未来的读者。他们会从评论中受益吗？在我自己的情况下，我只对我没有写的评论感到遗憾，很少对我写的不必要的评论感到遗憾。很多时候我都在想“我不可能忘记这一点”......并且做到了。

作为替代方案，您还可以维护带有完整注释的代码的单独副本，以及删除大部分/所有注释的发布版本。

于 2012-11-27T20:40:27.217 回答
1

无论你读过什么书说不应该写评论，你应该立即扔掉并永远忘记。我不在乎你是否是唯一会使用代码的人，你仍然应该记录它。

对我来说，如果您正在编写将被其他开发人员使用的代码，我会尝试坚持使用 PHPDoc (JavaDoc) 文档样式，这意味着您要尽可能彻底地记录每个类、方法、属性等。这带来的一个好处是，许多 IDE 实际上会使用此信息来完成代码，从而使您的应用程序更易于使用。

现在在代码块本身中，我认为您不需要注释每一行（尤其是那些很明显您在做什么的行），但是注释代码的不同部分、不同的逻辑分支等很有用。

我还建议的一件事是使用对其目的有意义的变量名（简单计数器除外）。人们常常变得可爱，想要使用 3-4 个字母的变量名，因为一些错误的观点认为这会使他们在打字时花费大量时间，或者使他们的代码更短。如果您需要一个长名称product_catalog_iterator来描述一个类，对我来说这比prodcatit或相似更好。

于 2012-11-27T20:44:42.717 回答
1

我相信不要写评论。而是编写自我注释的代码。我的意思是你的函数和变量描述了它们的作用。例如，您可以通过两种方式编写它：

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

或者你可以写

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

在这个例子中，第一个你不知道它在做什么，但是第二个，你确切地知道它在做什么。唯一一次我觉得需要评论是在你编写了真正的 hacky 代码之后，这些代码花了你很长时间才弄清楚如何去做，并且不太清楚它在做什么。然而，这应该介于两者之间。

文档不是一个好主意的原因是因为通常发生的情况是您在首次创建函数时以及在错误修复和维护之后编写了很好的注释。评论从未更新，现在评论说的是该功能没有做的事情，并且提供了混乱而不是帮助。

于 2012-11-27T20:47:53.317 回答