使用PHP7时，是否需要使用PHPDoc文档注释来记录方法？

Question

在PHP7中，当方法设置给定的参数类型和结果类型时，是否有必要在PHPDoc中再次记录它们？
自从

function foo(string $text): bool
{
    return true;
}

相当于

/**
 * @param string $text
 * @return bool
 */
function foo($text) {
    return true;
}

有必要复制这些信息吗？

/**
 * @param string $text
 * @return bool
 */
function foo(string $text): bool
{
    return true;
}

编辑：我不使用PHPDoc来生成我的代码文档，而是为了在PHPStorm的帮助下为我和我的同事保持方法的一致性。

- Marc Brillault

---

你是否运行过phpdoc来查看在声明参数和结果类型时它的行为？这将给你答案。 - John Conde

@JohnConde，PHPDoc 能否识别这个语法？ - Marc Brillault

@MarcBrillault 他想说的是：试一试，看看 - Xatenev

PHPDoc是一个文档生成工具，它能够为函数、参数等提供描述信息。IDE使用它来获取签名信息，这也是一个好的附带效应。即使您不使用PHPDoc生成代码文档，也可以通过查看IDE提取的信息来了解更多。如果需要添加信息，只需根据需要使用PHPDoc注释即可。在我看来，没有团队开发人员应该错过使用PHPDoc编写文档。即使独自开发时，PHPDoc也非常有帮助。 - Pinke Helga

Answer 1

docblock 是程序员用来解释函数功能的工具，虽然 PHP 解析器会忽略它（详见下面的编辑），但作为注释，最好在每个函数和方法上方添加 docblock，因为当别人（或你自己）阅读代码时，可以更容易地看出函数的作用。

IDE 通常使用 docblock 来进行自动完成功能，当块与代码不匹配时，string 和 :bool 将覆盖 docblock。

然而，

function foo(string $text): bool
{
    return true;
}

不等于

/**
 * @param string $text
 * @return bool
 */
function foo($text) {
    return true;
}

在第一个示例中，:bool 强制 foo() 返回 true 或 false，否则 PHP 将尝试将返回值强制转换为该类型或引发致命错误。

对于 $text 的类型提示 string 也是同样的道理。第一个参数必须是字符串类型的值，否则 PHP 将尝试将其转换为字符串或引发致命错误。

@return bool 和 @param string 不强制任何内容，只是表示期望的返回值是 true 或 false

看以下示例：

function foo(string $a) :bool
{
    var_dump($a); // string '10'
    return "string";
}

var_dump(foo(10)); // bool true

没有问题，PHP可以将10转换为字符串，并且"string"是true。但以下情况存在问题。

function foo(PDO $a) :bool 
{
    var_dump($a);
    return "string";
}

var_dump(foo(10)); // fatal error, 10 is not PDO and can not be cast to PDO

使用文档块可以使最后一个工作（可能会遇到其他问题，因为您可能正在尝试对PDO对象进行操作）

注意：PHP目前还不支持混合类型类型提示（即string|array），仍需通过在文档块中指定来完成。

编辑：
如@inwerpsel在评论中所指出的，我的说法--文档块被PHP解析器忽略--是不正确的。可以通过ReflectionClass在运行时读取文档块。

- Jelmergu

---

感谢您提供完整的答案！还感谢您提到了混合类型。 - Marc Brillault

谢谢，看到PHP会尝试转换类型，我感到很惊讶。在写这篇文章之前，我认为它总是会抛出致命错误，然后我去尝试了我的foo示例，结果让我感到惊讶。 - Jelmergu

如果使用declare(strict_types=1)来强制类型提示和返回值检查，那么你就可以放心地依赖于输入参数的真实类型为string而不是前面的int，并且返回值也会是真正的bool而不是前面的string。简单来说，使用declare(strict_types=1)，你的代码就更加安全了。 - ManInTheBox

“在每个函数和方法之上放置文档块是一个很好的惯例” - 完全不同意！首先：最佳实践是编写只做一件事情的函数。这也会让你更容易为这个函数命名。如果一个函数的名称已经告诉我它做什么，我就不需要额外的注释了。 - codeFareith

很不幸，你所建议的做法已经被许多开发人员采用了。这样做很烦人！例如，如果函数名为“getDataHandler”，为什么要在它上面放置一个文档块，其中写着“返回数据处理程序”？如果你发现自己处于需要解释代码的情况下，重新设计代码可能会更好。 - codeFareith

“它只是一条注释，会被 PHP 解析器忽略”这种说法并不准确。文档注释有自己的解析器标记：T_DOC_COMMENT。它将与常规的 T_COMMENT 一样处理，唯一的区别是可以使用 ReflectionClass API 在运行时访问它。 - inwerpsel

Answer 2

不，只有在实际记录某些内容时才添加PHPDoc，并且不要重复已经输入的变量提示或指定的返回值。 最新版本的PHP支持大多数PHPDoc指令的本地类型提示。

- Handsome Nerd