使用PHP7时，是否有必要使用PHPDoc记录方法？

在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的帮助下为我和我的同事保持方法的一致性。

docblock是程序员可以用来解释函数的功能的东西，它将被PHP解析器忽略（参见下面的编辑），因为它只是一个注释，所以最好在每个函数和方法上方放置docblock，因为当有人（或您）阅读代码时，更容易看到函数的功能

IDE通常使用docblock进行自动完成，但是当块与代码不匹配时，docblock将被

字符串

和

：bool

覆盖

然而

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

转换为字符串，并且

的“字符串”

是

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

使用docblock将使最后一个工作正常（可能会进一步遇到其他问题，因为您可能正在尝试使用PDO对象执行某些操作）

注意：PHP还不支持混合类型类型暗示（即字符串|数组），这仍然需要通过在docblock中指定来完成

编辑：

---

正如@inwerpsel在评论中指出的，我关于PHP解析器忽略docblock的说法是不正确的。docblock可以在运行时被读取。

您是否运行了phpdoc以查看在声明参数和结果类型时它的行为？这会给你答案。@johncode，PHPDoc难道不能识别这个语法吗？@MarcBrillault他想说的是：试试看，SeePHPDoc是一个文档记录者，即给出函数、参数aso的描述。IDE使用它来获取关于签名的信息，这是一个很好的副作用。“我不使用PHPDoc生成代码的文档”-因此，如果出于某种原因不需要它，只需查看IDE获取的信息。如果您想添加一些内容，只需根据需要使用PHPDoc注释即可。imho任何团队开发人员都不应错过使用PHPDoc编写文档的机会。在开发allone.Thank时，它甚至很有用。不过，我很惊讶地看到PHP会尝试转换这些类型。在写这篇文章之前，我认为它总是会抛出一个致命错误，然后我去尝试我的foo示例，如果您使用

declare（strict\u types=1）强制执行类型提示和返回值检查，结果会令人惊讶

然后您可以依赖输入参数的类型为真正的

string

，而不是上一示例中的

int

，并返回值real

bool

，而不是上一示例中的

string

。简单地说，使用

declare（strict_types=1）

你就安全了。“在每个函数和方法上方放置docblock是一个很好的做法”-完全不同意！首先：最佳实践是编写只做一件事的函数。这也会让你自己更容易给这个函数起一个有意义的名字。如果一个函数的名字已经告诉了我它是做什么的，我不需要额外的注释。不幸的是，你的建议是由很多开发人员完成的。而且很烦人！例如，如果函数名为“getDataHandler”，为什么要在其上放一个docblock，其中显示“返回数据处理程序”？如果你发现自己处于一种必须解释代码的情况下，最好考虑重构。“它会被PHP解析器忽略，因为它只是一个注释”，这是不正确的。doc注释有自己的解析器标记：T_doc_comment。它将以与常规T_注释相同的方式处理，唯一的例外是可以在运行时使用。