PHP中注释顺序的建议

Question

I currently use such order of annotations:

Code 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="")
{
 ...
}

Code 2:

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

Code 3:

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

At this time i don't use all annotations (probably all I use you can see in codes above).

And I wonder if in php is any suggested (preffered) order of annotations - or it is free matter of programmer (and then this question will be useless).

Answer 1

TLDR; It's a free matter

PHP coding standards differ on this. The best I can suggest is to pick a coding standard you like and run PHP CodeSniffer (https://github.com/squizlabs/PHP_CodeSniffer) against it and see what it suggest. Some coding standards require they be in a specific order and a specific spacing to your docblock annotations. Others are more relaxed and make no suggestions about docblock annotations what-so-ever.

To get 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

Some coding standards you might want to consider:

• http://www.php-fig.org/psr/psr-2/
• http://framework.zend.com/manual/1.12/en/coding-standard.coding-style.html
• http://pear.php.net/manual/en/rfc.header-comments.php

If you're worried about a document generators (like phpDocumentor) not being able to parse the docblock annotations, you can always check what annotations they support. I've never had a problem with phpDocumentor complaining about the ordering or formatting though.

As for custom annotations being used by libraries such as Doctrine, Symfony and PHPUnit, I've also never noticed the order having an impact on the parsing and processing.