问题 我什么时候应该在PHPDoc类型提示和docblocks中使用NULL?


我很困惑何时使用 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来包含整数。也就是说,如果没有为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 明确?


3293
2017-10-01 02:39


起源



答案:


在实践中,我倾向于让param标签只列出你的内容  传入。但是,对于返回标记,您确实需要列出可能返回的每种类型。这就是为什么我在两者上有所不同。

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

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


11
2017-10-01 14:06



我同意。在返回值中,指定所有可能的返回值。对于参数,只需指定预期值。如果null或字符串实际上不是你想要的字段,请不要在文档中将它们列为有效,因为php本身并不强制执行除数组和对象之外的任何类型的类型提示。 - Ray


答案:


在实践中,我倾向于让param标签只列出你的内容  传入。但是,对于返回标记,您确实需要列出可能返回的每种类型。这就是为什么我在两者上有所不同。

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

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


11
2017-10-01 14:06



我同意。在返回值中,指定所有可能的返回值。对于参数,只需指定预期值。如果null或字符串实际上不是你想要的字段,请不要在文档中将它们列为有效,因为php本身并不强制执行除数组和对象之外的任何类型的类型提示。 - Ray


是的,根据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,...如果参数数量不受限制


1
2017-10-01 03:22