在我学习 PHP 的过去 2 个月里，我发现了不止两种人们用来评论代码的风格！我没有看到太多的一致性......我认为这通常意味着艺术家在工作。所以我想知道：哪些有效的评论方式仍然可读/实用？并排查看 1 个位置的所有有效可能性将提供我正在寻找以改进评论的概述
/*
| This is what I now use (5chars/3lines) I name it star*wars
\*
【问题讨论】：
标签： php coding-style comments
引用注释手册：
PHP 支持“C”、“C++”和 Unix shell 样式（Perl 样式）cmets。例如：
<?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
?>
一般来说，你会想要avoid using comments in your sourcecode。引用 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) { …
如果剩余的方法签名清楚地传达了它的作用，我认为你可以省略 Short 和 Long Desc。但是，这需要一定的纪律和知识来实际编写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 文档。重要的是，无论您决定做什么，都要始终如一地去做。
【讨论】：
if (FALSE === $date->isInSummerPeriod()) yoda style ftl。除此之外，当一个函数期望返回一个 true 时，使用 if(!func())...
isNotInSummerPeriod，我个人认为它不是最理想的，因为否定有点难以掌握。我使用 Yoda 是因为我经常忽略 if (!$date->… 中的 !。此外，将参数与左手进行比较可以避免在 if($foo = TRUE) 等语句中意外赋值，尽管不可否认，这不适用于上面的示例，但我现在已经习惯了 Yoda，所以我一直使用 is。随意使用!或notInSummer或切换比较。
在我看来，它们每个都具有同等可读性。
我同时使用单线和多线 cmets。
以灰色突出显示，它们始终可见并且与其他代码不同。
我之前没有发现 cmets 可读性存在任何问题
【讨论】：
使用 phpdoc guidelines 进行评论是很常见的。这包括用于生成文档的注释。
【讨论】：
您绝对应该使用 phpdoc 标准。这是针对初学者的quick start。
我相信你见过这样的 cmets：
/**
* 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 开发人员轻松阅读，还可以生成漂亮的文档。
【讨论】：