Question

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

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

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

为了更清楚 - 我应该：

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

Answer 1

你应该：

在每个课程之前编写文档
在每种方法之前编写文档
为每个公共方法编写@param，@ return ...

对每行代码的评论都不太必要，但我建议他们使用代码行，否则这些行代码将不清楚或模糊不清。

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

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

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

我应该写PHP评论/文档

5 个答案: