PHP：评论代码

有理论上的问题。

我使用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 
}

我这样做是正确的方法是什么？在代码中插入注释是否有任何标准？

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

问候，汤姆

来源

2010-08-11 Tom

如果“检查，如果变量名是大于零”是注释的一个真实的例子，你肯定做错了。 – 2010-08-11 19:39:44

你可以下定决心你的问题是什么？你原来的问题是问是否有任何标准（比特模糊）。然后你在编辑中说，你只是在问是否是评论你的代码的好习惯......然后在对另一个答案的评论中你说'我也看到了不同的评论方法，但是我问的是否是正确的将这种评论放入代码中，它明确要求*种类的评论...所以你想知道什么？ – 2010-08-11 19:51:03

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

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

因此，记录代码的最好方法是让它真正清楚！我会写你这样的代码：

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

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

此代码不需要评论，因为在所有它是非常简单的了解吧！

好了，反正当我必须写评论（几乎没有），我去与//格式，但我认为这并不重要。

顺便说一句，看看叔叔的这真棒视频鲍勃http://bit.ly/AYqFT

来源

2010-08-11 19:52:28 Alfwed

一些（如果不是大多数）PHP程序员使用注释他们的代码双斜线法（//）。实际上没有标准，我看到有人在线的开头使用英镑符号（#）发表评论，还有其他人用/*和*/注释掉块。

来源

2010-08-11 19:37:53 esqew

感谢您的评论。我也看到了不同的评论方式，但我是问，如果是正确的把那种注释到代码:) – Tom 2010-08-11 19:40:56

// Check if variable_name is greater than zero

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

作为一般（语言无关）的经验法则，编写大多是自我记录（通过使用描述性名称，避免不明显的快捷方式等）的代码，并且只评论你为什么做一些看起来错误/奇怪的事情。

来源

2010-08-11 19:40:41 delnan

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

除此之外，我没有看到双斜线注释类型没有错。

来源

2010-08-11 19:40:57

个人而言，我很谨慎地内联文档（尽管我在宗教上将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; 
}

来源

2010-08-11 19:44:16 ircmaxell

IMO意见不应该解释的代码没有什么，只是为什么（或其他事情绝对需要去了解它）。解释代码的作用是重复信息，应该始终避免。 – 2010-08-11 19:46:00

@Arve Systad：我也是这么做的（当然，99.95％的时间）。我确实认为有些时候你可能想要解释如何（这就是为什么我加入OP）。但你的理由更好。我从我的回答中编辑了这种情绪...... – ircmaxell 2010-08-11 20:12:22

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

但是，随着意见的唯一标准是一致！保持一致，你不必担心如何混淆评论（仅限于何时使用它们）。

来源

2010-08-11 20:00:13 palswim

PHP：评论代码

回答

相关问题