什么时候应该在 PHPDoc 类型提示和文档块中使用 NULL？答案

【问题标题】：When should I use NULL in PHPDoc type hints and docblocks?什么时候应该在 PHPDoc 类型提示和文档块中使用 NULL？
【发布时间】：2012-09-21 22:16:11
【问题描述】：

在使用 PHPDoc 描述变量时，我对何时使用 null 作为类型感到困惑。类型提示是否应该描述外部调用者预期和遵守的希望和期望，还是应该记录变量的所有可能类型，即使希望它在实践中是一种非常具体的类型？

示例 1：默认值。以下函数只需要非空值。但是如果没有传递任何值，它默认为null 并明确地检查它以确定是否传递了任何东西，并为这种情况返回一个特殊值。希望没有外部调用者会传递除整数之外的任何内容。 null 应该在下面的@param 类型中使用，还是应该只指定int，因为这是我们想要传递的内容，如果有任何传递？

/**
 * @param int|null $bar
 */
function foo($bar = null) {
  if(is_null($bar)) { 
    return 'ABC';
  }

  return doSomething($bar);
}

示例 2：实例属性。我们只希望 $bar 包含整数。也就是说，如果没有为 bar 设置任何内容，则此实例属性的默认 PHP 值为 null。我是否需要在每个使用 $bar 的地方都考虑到这一点，可能的 null 类型如下？

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 的值，否则我应该避免指定它？

【问题讨论】：

标签： php phpdoc docblocks

【解决方案1】：

在实践中，我倾向于让参数标签只列出您想要传入的内容。但是，对于返回标签，您确实需要列出可能返回的每种类型。这就是为什么我对两者有不同的原因。

由于 PHP 不是强类型的，即使你说“只传递一个 int”，你的方法仍然需要确保它没有传递意外的东西。仅仅因为方法代码试图处理接收其他类型，你不希望你的文档告诉你的用户“当然，你可以给我一个 NULL，我会为你做一些事情”。您希望您的文档说“给我一个整数，句号”。

在考虑返回值时，您的用户确实确实需要知道可能从您的方法返回的每种潜在返回类型，因为他们确实需要在代码中覆盖其基础以处理您的方法可能返回的所有类型。

【讨论】：

我同意。在返回中，指定所有可能的返回值。对于参数，只需指定预期值。如果 null 或 string 不是您真正想要的字段，请不要在文档中将它们列为有效，因为 php 本身不会对数组和对象以外的任何内容强制执行类型提示。

【解决方案2】：

是的，根据 PHPDoc 标准，您应该在任何地方都包含 null（当然，如果适用的话）

请看这里：http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html

数据类型应该是有效的 PHP 类型（int、string、bool 等），a 对象类型的类名，或者简单地“混合”。此外，您可以通过用分隔它们列出单个参数的多个数据类型管道（例如“@param int|string $p1”）。您可以记录参数列出的或将由标准 PHP 解析的任何可选参数函数 func_num_args()/get_func_arg()。推荐的名称格式 func_get_arg() 列出的参数是： $paramname 如果只有一个参数 $paramname,... 如果参数个数不限

【讨论】：