Зачем объявлять тип переменной PHP в комментарии?

Я новичок в PHP, и я только начал использовать NetBeans для разработки моего PHP-кода.

Синим цветом, когда я ввел переменную в запрос, появилось диалоговое окно и попросило заполнить комментарий для хранения типа переменной. Я провел некоторое расследование и обнаружил, что это, по-видимому, популярная функция NetBeans, но я не мог найти никакой информации, чтобы объяснить мне, почему это было так.

Почему кто-то хочет поместить тип переменной PHP в комментарий? Используется ли это для разработки или действительно ли это полезно для самого кода? Является ли он интегральным или необязательным?

Ответ 1

Добавление типа в тег @var внутри комментария метода позволит NetBeans показать вам завершение кода. Это, конечно, необязательно, но всегда полезно полностью документировать свой код.

Изменить: Совет для NetBeans для автоматического создания комментариев для вас - использовать расширение /**. Для этого просто поместите курсор над свойством или методом, который вы хотите документировать, и введите /**, а затем нажмите клавишу ENTER. Это расширит комментарий к стилю phpDoc и добавит соответствующие теги.

Изменить 2: Тег @var можно использовать для свойства, и вы можете использовать тег @param для метода, чтобы добиться такого же эффекта с параметрами, переданными в метод.

Использование тега @var для свойства даст подсказки кода при использовании свойства в любом месте, где оно видно:

/**
 *
 * @var My_Type
 */
private $_myProperty;

Использование тега @param метода даст вам подсказки кода при использовании параметра внутри метода:

/**
 *
 * @param My_Type $obj 
 */
public function myMethod($obj) {

}

Другим способом достижения аналогичного эффекта, а также обеспечения степени безопасности типов является использование PHP type hinting механизм:

public function myMethod(My_Type $obj) {

}

Обратите внимание, что этот метод имеет тип, указанный в сигнатуре метода. Теперь NetBeans предоставит такое же завершение кода внутри метода, который доступен с помощью тега @param, а PHP будет генерировать E_RECOVERABLE_ERROR, если тип, переданный в этот метод, не является тем же типом, который был указан. См. документацию PHP относительно ошибок и способы их обработки, если вам интересно узнать больше об этой ошибке.

Ответ 2

Я думаю, вы говорите о чем-то подобном:

/**
 * @var SimpleXMLElement $xml
 */
private $xml;

Это так называемый комментарий phpDoc. Он позволяет создавать документацию API (как это, например,). Кроме того, большинство IDE, включая Eclipse и NetBeans, также поддерживают этот синтаксис и обеспечивают динамическое завершение кода и т.д.

Ответ 3

Если вы хотите объявить тип переменной в случае, когда переменная не является свойством класса, а просто переменной, которая содержит некоторое возвращаемое значение, используйте одиночные комментарии, а затем @var, а затем имя переменной и, наконец, следует тип этой переменной. Например:

/* @var $errorMessage NotificationMessage */
$errorMessage= $allMessages->rewind()->current();

сообщит NetBeans или PhpStorm, что $errorMessage является экземпляром NotificationMessage, и вы должны получить завершение кода для этой переменной.

Ответ 4

Несмотря на то, что netbeans используют его для автозаполнения, это часто полезно для документирования вашего кода:

В этом случае вы знаете, что получает этот метод и что он возвращает, но внутри кода, о котором вы не знаете, что происходит

/**
 * Returns some stuff
 * @param string $someObj
 * @return array
 */
public function someMethod($someObj) {
    $factoredObj = getObject($someObj); //you are not sure what type it returns
    $resultArray = $factoredObj->toArray();
    return $resultArray;
}

Вы можете прокомментировать это с помощью /* @var $variable type */ внутри кода

/**
 * Returns some stuff
 * @param string $someObj
 * @return array
 */
public function someMethod($someObj) {
    /* @var $factoredObj someType */
    $factoredObj = getObject($someObj);
    $resultArray = $factoredObj->toArray();
    return $resultArray;
}

или

$factoredObj = getObject($someObj); /* @var $factoredObj someType */

Ответ 5

Поскольку PHP - это язык с отложенным/утиным языком, когда вы создаете большую программу, подсказки типа могут помочь вам или другим понять, что происходит, если возникнет проблема. Например, ожидая смешанный тип и отправляя целое число.