什么是有效的&；PHP5中评论的可读方法？

在过去的两个月里，我一直在学习PHP，我已经确定了两种以上的风格，人们用来评论代码！我没有看到太多的一致性。。。我想这通常意味着艺术家在工作。所以我想知道：什么是仍然可读/实用的有效评论方式？在一个地方并排看到所有有效的可能性，这将提供我希望改进评论的概述

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

---

您肯定应该使用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开发人员易于阅读，而且还可以生成漂亮的文档。

使用phpdoc进行评论是很常见的。这包括用于生成文档的注释。

引用手册中的注释：

PHP支持“C”、“C++”和Unix shell风格（Perl风格）注释。例如：

应该改写为

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

您有时会遇到的另一种注释类型是分隔符注释，例如

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

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

或

这些通常表明它们所用的代码做得太多了。如果您在一个类中发现了这一点，请检查该类的责任，并查看是否可以将该类的某些部分更好地重构为独立类

对于API文档，常用的符号是，例如

我认为，如果剩余的方法签名清楚地传达了它的功能，那么可以省略Short和Long Desc。然而，这需要一定的纪律和如何实际写作的知识。例如，以下内容是完全多余的：

/**
 * 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文档。重要的是，无论你决定做什么，都要始终如一地去做。

在我看来，每一个都是同样可读的。
我同时使用一行和多行注释

它们以灰色突出显示，始终可见，并与其他代码不同。

---

我以前从未见过评论可读性有任何问题

。。。而且许多IDE也可以解析它们：）这使得代码完成成为一个强大的工具。是否有一个编辑器可以突出显示您的评论？@Colonel yessir:DreamWeaver&Notepad2 Bookmark Edition会给它们着色。不过，写评论的数量和风格让我觉得它们可读，或者不可读。我猜一个好的懒散的评论者首先想到的是简短的基本评论，这比看起来要困难得多。我有时甚至无法解读自己的评论。这正常吗？

if（FALSE===$date->isInSummerPeriod（））

yoda风格的ftl。除此之外，当一个函数期望返回一个true时，如果（！func（））…一个doublet，lol:）使用

if（！func（））

）是很好的选择，但是避免注释非常好，这是一个非常出色的答案。@thift@Col重构书实际上建议使用否定形式

isnotimmerperiod

，我个人认为这是次优的，因为否定更难理解。我使用尤达是因为我经常忽略

在
if（！$date->…
）中。另外，将参数置于左侧进行比较可以避免在
if（$foo=TRUE）之类的语句中意外赋值
，虽然这并不适用于上面的例子，但我现在已经习惯了Yoda，所以我使用的是一致的。请随意使用
！
或
而不是不完整的
或切换比较。更改了summerPeriod例子以避免进一步讨论上述论点。@Gordon，一定是偶然的我的问题从没有回答到有回答。我一定是喝醉了！干杯！
/**
 * Short Desc
 *
 * Long Desc
 * 
 * @param  type $name description
 * @return type       description
 */
 public function methodName($name) { …

/**
 * 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() { …