phpdoc — подсказка типа PHP — код и аннотации

Question

phpdoc — подсказка типа PHP — код и аннотации

PHP 5 может сделать немного (ограничено) тип подсказки, однако, мне кажется, что в реальных проектах типы обычно описываются в комментариях к документам. Например, вместо этого:

/**
* Test method
*/
function test(SomeType $param1) {
...
}

там будет чаще

/**
* Test method
*
* @param SomeType param1
*/
function test($param1) {
...
}

Каковы преимущества и недостатки двух подходов? И если я прав в предположении, что метод PhpDoc является более распространенным, то почему? Почему люди больше не используют встроенную языковую функцию?

редактировать: третий вариант — использовать оба подхода вместе:

/**
* Test method
*
* @param SomeType param1
*/
function test(SomeType $param1) {
...
}

Тем не менее, я лично не видел, чтобы это использовалось слишком часто (рассматривал библиотеки, такие как Symfony или PHPUnit), и это также похоже на выполнение некоторой работы, если честно, не так много дополнительной выгоды. Может быть, поэтому его не видят чаще.

4

php phpdoc type-hinting

Решение

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

Лично я бы использовал оба.

Первый вариант хорош для контроля того, какие объекты вы передаете методу. Второй обычно может быть добавлен автоматически любой современной IDE, и это делает ваш код более читабельным.

1

Источник

Accepted Answer

Во-первых: PHP-шрифты могут отличаться от PHPDoc. Отличия (как минимум):

Скалярные типы. В PHP вы не можете подсказывать скалярные типы, в то время как ничто не мешает вам подсказывать
```
/**
* @param string $param Param description
*/
```
Массив намеков. В PHPDoc вы можете намекнуть, что этот параметр (или возвращаемое значение) является массивом чего-либо. Это было бы:
```
/**
* @param ClassName[] $param Param description
*/
```
и смысл этого — массив экземпляров ClassName, Это чрезвычайно полезно, когда дело доходит до возвращаемого типа (потому что тогда IDE может делать замены для методов на итерации этого массива, и, следовательно, вы будете знать, что вы делаете правильные вещи или нет). Тем не менее, в PHP вы можете только напечатать это как
```
function functionName(array $param) { /*...*/ }
```
поэтому невозможно будет понять, что является фактическими элементами массива. Для вашей информации есть соответствующий RFC для набора текста как массива некоторых элементов, который в настоящее время отклонен — но может быть в будущем такая возможность появится в PHP.

Но, с другой стороны, использование PHP-шрифтов — это все-таки другое, и обычно вы должны делать и то и другое — поэтому, если есть возможность как-то намекнуть в PHP (как в примере с массивом выше) — сделайте это и добавьте также блок PHPDoc. PHP typehint позволяет навязывать поведение на уровне языка, в то время как PHPDoc является только «информационным» источником, он служит только информационной цели и не может предотвратить передачу недопустимого типа аргумента.

3