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

Question

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

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

Почему кто-то хочет разместить тип переменной PHP в комментарии? Он предназначен для разработки или действительно полезен для самого кода? Это цельное или необязательное?

Answer 1

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

Редактировать: Совет для NetBeans по автоматической генерации комментариев для вас - использовать * 1006.* расширение.Для этого просто поместите курсор над свойством или методом, который вы хотите задокументировать, и наберите /**, а затем нажмите клавишу 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 об ошибках и о том, как их устранять, если вы хотите узнать больше об этой ошибке.

Answer 2

Полагаю, вы говорите о чем-то таком:

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

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

Answer 3

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

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

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

Answer 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 */

Answer 5

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