Я смущен тем, когда использовать null как тип при описании переменных с помощью PHPDoc. Предполагают ли типы намеки, чтобы описать надежды и ожидания для внешних абонентов, чтобы их предвидеть и соблюдать, или они должны документировать все возможные типы переменных, даже если надежда на то, что это будет один очень специфический тип на практике?
Пример 1: значения по умолчанию. Следующая функция ожидает только ненулевые значения. Но если значение не передано, оно по умолчанию равно null и явно проверяет его как способ определить, было ли передано или нет, и возвращает специальное значение для этого случая. Надеюсь, никакой внешний вызывающий абонент не передаст ничего, кроме целого. Должен ли null использоваться в типе @param, как указано ниже, или должен указывать только int, так как это то, что мы хотим передать, если что-либо передано?
/**
* @param int|null $bar
*/
function foo($bar = null) {
if(is_null($bar)) {
return 'ABC';
}
return doSomething($bar);
}
Пример 2: свойства экземпляра. Мы хотим, чтобы $bar содержал целые числа. Тем не менее, если для бара ничего не установлено, значение PHP по умолчанию для этого свойства экземпляра равно null. Нужно ли мне учитывать это в каждом месте, где используется $bar, с возможным нулевым типом, как показано ниже?
class Foo {
/**
* @var int|null
*/
public $bar;
/**
* @param int|null $bar
*/
public setBar( $bar) {
$this->bar = $bar;
}
/**
* @return int|null
*/
public function getBar() {
return $this->bar;
}
}
В основном, я нахожу, что улавливаю почти каждое объявление @param и @var с помощью |null, потому что технически это может быть это значение. Но на практике этого не должно быть. Должен ли я ожидать, что почти все мои типы будут содержать возможность null или это должно быть принято, и я должен избегать указания его, если я не ожидаю установить или получить значение null явно?