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 Code Sniffer：

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

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

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

对于Doctrine，Symfony和PHPUnit等库使用的自定义注释，我也从未注意到该订单会对解析和处理产生影响。

PHP中注释顺序的建议

1 个答案: