php - 什么时候应该在 PHPDoc 类型提示和文档 block 中使用 NULL？

Question

在使用 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 的值> 明确地？

Answer 1

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

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

在考虑返回值时，您的用户确实非常需要了解您的方法可能返回的每一种潜在返回类型，因为他们确实需要在代码中涵盖他们的基础以处理您的方法可能返回的所有类型。