PHP 类型提示 - 代码与注释

Question

PHP 5 可以做一些（有限的）类型提示，但是，在我看来，在实际项目中，类型通常在文档注释中描述。 例如，而不是这样：

/**
 * Test method
 */
function test(SomeType $param1) {
    ...
}

更常见的是

/**
 * Test method
 *
 * @param SomeType param1
 */
function test($param1) {
    ...
}

这两种方法的优缺点是什么？ 如果我认为 PhpDoc 方法更常见是正确的，为什么会这样？ 为什么人们不更多地利用内置语言功能？

编辑：第三个选项是结合使用两种方法：

/**
 * Test method
 *
 * @param SomeType param1
 */
function test(SomeType $param1) {
    ...
}

但是，我个人还没有看到它经常使用（查看了 Symfony 或 PHPUnit 之类的库），而且老实说，这似乎也做了一些工作，但没有太多额外的好处。 也许这就是为什么它不经常出现的原因。

Answer 1

第一件事：PHP 类型提示具有与 PHPDoc 不同的提示能力。 差异是（至少）：

• 标量类型。 在 PHP 7.1 之前，您不能提示标量类型，而没有什么可以阻止您提示

  /** * @param string $param Param description */

• 提示数组。 在 PHPDoc 中，您可以提示，该参数（或返回值）是某个数组。 这将是：

   /** * @param ClassName[] $param Param description */

  其含义是 - ClassName的实例数组。 这在返回类型方面非常有用（因为 IDE 可能会在该数组的迭代中替换方法，因此，您将知道自己是否在做正确的事情）。 但是，在 PHP 中，您只能将其键入提示为

  function functionName(array $param) { /*...*/ }

  所以不可能意识到数组的实际元素是什么。 对于您的信息，有一个相应的RFC用于将类型提示作为某些元素的数组，目前被拒绝 - 但将来这种可能性可能会出现在 PHP 中。

但是，另一方面，使用 PHP typehints 仍然是不同的事情，通常你应该两者都做 - 所以，如果可以在 PHP 中以某种方式提示（如上面的数组示例） - 这样做，并添加 PHPDoc 块。 PHP typehint 允许您在语言级别强制执行行为，而 PHPDoc 只是“信息”源，它仅服务于信息目标，不能防止传递非法参数类型。

Answer 2

我个人会同时使用两者。

第一个选项有利于控制传递给方法的对象。 Second 通常可以由任何现代 IDE 自动添加，它使您的代码更具可读性。