PHP 中注释顺序的建议

Question

我目前使用的注释顺序是这样的：

代码 1：

/**
 * sets elements for main (top), secondary (sub1) level and tertiary (sub2) level;
 * prevents sharing of content with previous instances
 *
 * @param string $TopElement
 * @param string $SubElement1
 * @param string $SubElement2
 *
 * @return void
 *
 * @throws MarC_Exception if top element was not set
 * @throws MarC_Exception if sub1 element was not set
 * @throws MarC_Exception if sub2 element was not set
 * @throws MarC_Exception if all elements were set the same
 */
public function __construct($TopElement="", $SubElement1="", $SubElement2="")
{
 ...
}

代码 2：

/**
 * elements used for creation of code
 *
 * @static
 * @var array
 */
protected $Elements = array();

代码 3：

/**
 * @package ...
 *
 * @author ...
 * @copyright ...
 *
 * @license ...
 *
 * generation of advanced select menu
 */

目前我没有使用所有注释（可能我使用的所有注释您都可以在上面的代码中看到）。

而且我想知道 php 中是否有任何建议的（首选的）注释顺序 - 或者它是程序员的自由事项（然后这个问题将毫无用处）。

Answer 1

TLDR；这是一件免费的事情

PHP 编码标准对此有所不同。我能建议的最好的方法是选择一个你喜欢的编码标准，然后运行 PHP CodeSniffer (https://github.com/squizlabs/PHP_CodeSniffer) 反对它，看看它有什么建议。一些编码标准要求它们按特定顺序排列，并与您的文档块注释保持特定间距。其他人则更轻松，对 docblock 注释没有任何建议。

获取PHP代码嗅探器：

$ curl -OL https://squizlabs.github.io/PHP_CodeSniffer/phpcs.phar
$ php phpcs.phar -h
$ php phpcs.phar --standard=[STANDARD_CHOICE] /path/to/project

您可能要考虑的一些编码标准：

如果您担心文档生成器（如 phpDocumentor）无法解析文档块注释，您可以随时查看它们支持的注释。我从来没有遇到过 phpDocumentor 抱怨排序或格式的问题。

至于 Doctrine, Symfony and PHPUnit 等库使用的自定义注释，我也从未注意到顺序对解析和处理有影响。

PHP 中注释顺序的建议

Suggestions for order of annotations in PHP

php

annotations