Question

美好的一天，

得到了理论上的问题。

我正在使用KohanaPHP框架创建一个简单的应用程序，只是fyi。这是我第一次使用框架而且有一个 - 对于你们中的一些人来说可能很愚蠢 - 问题。

在开发类或函数时，我正在使用DocBlock来表达我的代码。只是想知道在使用框架时我应该如何评论我的代码？我的意思是编写代码的某些部分，而不是整个控制器。

基本上，我使用以下方法：

// Check if variable_name is greater than zero
if($this->var > 0) {
    // do something
} else {
    // do something
}

if( $result ) {
    // display confirmation message
} else {
    // display errors
}

我做得对吗？在代码中插入注释有什么标准吗？

编辑：让我解释一下，我没有使用像“检查变量是否大于零”之类的评论。我只是想知道将注释放入代码是否是一种好习惯。

此致汤姆

Answer 1

与评论的视觉风格无关，但像“检查变量名是否大于零”这样的评论本身就是一个不好的评论。它所做的就是复制下面一行的信息。代码应包含变量，函数和其他可以读取的内容的名称，以了解正在发生的事情。

除此之外，我认为双斜杠评论类型没有错。

Answer 2

// Check if variable_name is greater than zero

这样的评论毫无价值。我只知道很少的PHP，即使我对它一无所知，我也可以在查看该行之后立即告诉（或者至少非常自信地猜测）。

作为一般的（与语言无关的）经验法则，编写主要是自我记录的代码（通过使用描述性名称，避免非显而易见的快捷方式等），并仅评论为什么你做了看起来错误/奇怪的事情。

Answer 3

就个人而言，我谨慎地记录内联（我确实将doc-blocks放在方法，类和成员变量中）。我相信代码本身应该尽可能地自我记录。

有时您需要做一些不明显甚至可能违反直觉的事情。这是内联评论的时间。试着解释一下代码块没有做什么，但是为什么它会这样做。

Phing的CodeCoverageReportTask类中有一个很好的例子：

// Strange PHP5 reflection bug, 
//     classes without parent class or implemented interfaces 
//     seem to start one line off
if ($reflection->getParentClass() == NULL 
    && count($reflection->getInterfaces()) == 0)
{
    unset($coverageInformation[$classStartLine + 1]);
}
else
{
    unset($coverageInformation[$classStartLine]);
}

另一个很好的一点就是下面几行：

// PHP5 reflection considers methods of a parent class to be part 
//     of a subclass, we don't
if ($method->getDeclaringClass()->getName() != $reflection->getName())
{
    continue;
}

Answer 4

一些（如果不是大多数）PHP程序员使用双斜杠方法（//）来评论他们的代码。确实没有标准，我看到有人在一行的开头使用井号（#）进行评论，而其他人则使用/*和*/注释掉块。

Answer 5

评论是骗子！ 注释的问题是您必须在更新代码时更新它们。如果不这样做，最终会得到如下代码：

// sum $a and $b
$x = $a * $a - $b;

因此，记录代码的最佳方法是使其非常清晰！我会写这样的代码：

if ( isPositive(3) ) {
    doA();
} else {
    doB();
}

if( $result ) {
    displayConfirmationMsg();
} else {
    displayErrors();
}

此代码根本不需要注释，因为理解起来非常简单！

嗯，无论如何，当我必须写评论（几乎从不）时，我会使用//符号，但我认为这并不重要。

顺便说一句，看看这个非常棒的博客http://bit.ly/AYqFT

的视频

Answer 6

我完全同意评论不应该解释代码的，只有为什么。但是，在代码中添加必要的注释绝对是一种好的做法。当我回去查看我的一些代码（php或其他代码）时，我希望我的评论更清楚。

但是，评论的唯一标准是一致性！保持一致，你不必担心混淆评论（只关注何时使用它们）。

PHP：评论代码

6 个答案: