Предложения по порядку аннотаций в Stack Overflow

Question

Предложения по порядку аннотаций в Stack Overflow

В настоящее время я использую такой порядок аннотаций:

Код 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 какой-либо предложенный (предпочтительный) порядок аннотаций — или это свободный вопрос программиста (и тогда этот вопрос будет бесполезен).

0

annotations php

Решение

Другие решения

Других решений пока нет …

Источник

Accepted Answer

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, Я также никогда не замечал, что заказ оказывает влияние на синтаксический анализ и обработку.

1