PHP5中注释的有效和可读方法是什么？

Question

在过去的两个月中，我一直在学习PHP，我发现人们用来注释代码的风格不止两种！我没有看到很多一致性...这通常意味着艺术家正在工作。所以我想知道：哪些有效的注释方式仍然可读/实用？将所有有效的可能性放在一起比较，将提供我所需要的概述，以改进注释。

/*
|  This is what I now use (5chars/3lines) I name it star*wars
\*

- Sam

---

你有一个可以突出显示注释的编辑器吗？ - Your Common Sense

@Colonel 是的先生：DreamWeaver和Notepad2书签版都支持着色。然而，写注释的数量和风格使它们对我来说难以阅读。我猜一个好的懒惰注释者首先考虑简短的基本注释比看起来更困难。有时我甚至无法解码自己的注释。这正常吗？ - Sam

Answer 1

引用评论手册：

PHP支持'C'，'C++'和Unix shell风格（Perl风格）的注释。例如：

<?php
    echo 'This is a test'; // This is a one-line c++ style comment
    /* This is a multi line comment
       yet another line of comment */
    echo 'This is yet another test';
    echo 'One Final Test'; # This is a one-line shell-style comment
?>

通常情况下，你会希望避免在源代码中使用注释。引用Martin Fowler的话:

当你感觉需要写注释时，首先尝试重构代码，使得任何注释都变得多余。

这意味着：

// check if date is in Summer period
if ($date->after(DATE::SUMMER_START) && $date->before(DATE::SUMMER_END)) {

应该重写为

if ($date->isInSummerPeriod()) { …

你有时会遇到另一种注释类型，即分隔符注释，例如：

// --------------------------------------------

或者

################################################

这通常表明它们所在的代码正在执行过多的任务。如果您发现这种情况出现在一个类中，请检查该类的职责，并查看其中是否有一些部分最好重构为独立的类。

至于API文档，常用的符号是PHPDoc，例如：

/**
 * Short Desc
 *
 * Long Desc
 * 
 * @param  type $name description
 * @return type       description
 */
 public function methodName($name) { …

我认为，如果剩余的方法签名清晰地传达了其功能，那么可以省略“简短描述”和“长描述”。然而，这需要一定的纪律和知识，以实际编写Clean Code。例如，以下内容完全是多余的：

/**
 * Get the timestamp property
 *
 * The method returns the {@link $timestamp} property as an integer.
 * 
 * @return integer the timestamp
 */
 public function getTimestamp() { …

应缩短为

/**
 * @return integer
 */
 public function getTimestamp() { …

不用说，是否选择完整的API文档也取决于项目。我期望任何我可以下载和使用的框架都有完整的API文档。重要的是，无论你决定做什么，都要保持一致。

- Gordon

---

如果条件为假并且日期不在夏令时期间，代码应该这样写：if(FALSE === $date->isInSummerPeriod())。此外，当函数返回真时，使用if(!func())是完全可以的… 请注意，这里使用了 Yoda 风格。 - ThiefMaster

一个双音词，哈哈 :) 避免注释的建议非常好，是这个非常出色答案中的一颗闪亮之星。 - Your Common Sense

@Thief @Col 《重构》一书实际上建议使用否定形式的 isNotInSummerPeriod，但我个人认为这种否定形式有些难以理解。我使用 Yoda 是因为我经常忽略 if (!$date->… 中的 !。此外，将要比较的参数放在左手边可以避免在像 if($foo = TRUE) 这样的语句中意外赋值，尽管必须承认，这并不适用于上面的例子，但我已经习惯了 Yoda，所以我一直使用它。请随意使用 ! 或 notInSummer 或切换比较方式。 - Gordon

将summerPeriod示例更改以避免进一步讨论上述参数。 - Gordon

@Gordon，可能是在将我一些未回答的问题归档为已回答时出错了。我肯定喝醉了！干杯！ - Sam

Answer 2

您应该绝对使用phpdoc标准。这里是针对初学者的快速入门。

我相信您已经见过像这样的注释：

/**
 * example of basic @param usage
 * @param bool $baz 
 * @return mixed 
 */
function function1($baz)
{
   if ($baz)
   {
      $a = 5;
   } else
   {
      $a = array(1,4);
   }
   return $a;
}

这种注释方式不仅易于大多数PHP开发人员阅读，而且还可以生成漂亮的文档。

- alexn

---

许多集成开发环境（IDE）也可以解析它们 :) 这使得代码补全成为一种强大的工具。 - KingCrunch

Answer 3

对我来说，它们每一个看起来都同样易读。
我同时使用单行注释和多行注释。

它们以灰色高亮显示，始终与其他代码区分开来。
在此之前，我从未遇到过关于注释易读性的问题。

- Your Common Sense

Answer 4

使用phpdoc 指南 进行注释是非常常见的。这包括用于生成文档的注解。

- halfdan