В настоящее время я использую такой порядок аннотаций:
Код 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 какой-либо предложенный (предпочтительный) порядок аннотаций — или это свободный вопрос программиста (и тогда этот вопрос будет бесполезен).
TLDR; Это свободный вопрос
Стандарты кодирования PHP отличаются в этом. Лучшее, что я могу предложить, это выбрать понравившийся вам стандарт кодирования и запустить PHP CodeSniffer (https://github.com/squizlabs/PHP_CodeSniffer) против этого и посмотрим, что он предлагает. Некоторые стандарты кодирования требуют, чтобы они были в определенном порядке и с определенным интервалом для ваших аннотаций докблока. Другие более расслаблены и не делают никаких предположений относительно аннотаций докблока.
Чтобы получить 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) не имея возможности анализировать аннотации докблока, вы всегда можете проверить, какие аннотации они поддерживают. У меня никогда не было проблем с phpDocumentor, который жаловался на порядок или форматирование.
Что касается пользовательских аннотаций, используемых библиотеками, такими как доктрина, Symfony а также PHPUnit, Я также никогда не замечал, что заказ оказывает влияние на синтаксический анализ и обработку.
Других решений пока нет …