如何在PHP7.4中使用DocBlocks？

Question

一般来说，在PHP中使用DocBlock是最佳实践之一。对于PHP的早期版本(比PHP7.3或特别是7.4)，它非常有用。它告诉开发人员类属性类型、参数类型和方法返回的值(在PHP中缺少严格的类型)。

让我们说，在PHP5.6中，代码可以如下所示：

namespace App\Service\Catalog\Category;

use App\Entity\Catalog\Category\Category;
use App\Repository\Catalog\Category\CategoryRepository;

class CategoryService
{
    /** @var CategoryRepository */
    private $categoryRepository;

    /** @var int */
    private $currentNestingLevel = 1;

    /**
     * CategoryService constructor.
     * @param CategoryRepository $categoryRepository
     */
    public function __construct(Category $categoryRepository)
    {
        $this->categoryRepository = $categoryRepository;
    }

    /**
     * @param $parentCategoryId
     * @return array
     */
    public function getCategoriesDataByParentCategoryId($parentCategoryId)
    {
        $categories = $this->categoryRepository->getByParentCategoryId($parentCategoryId);
        $categoriesData = [];

        foreach ($categories as $category) {
            $categoriesData[] = $this->getCategoryData($category);
        }

        return $categoriesData;
    }
}

但在本例中，当我们使用PHP7.4时，这些DocBlocks没有提供任何其他信息：

namespace App\Service\Catalog\Category;

use App\Repository\Catalog\Category\CategoryRepository;

class CategoryService
{
    private CategoryRepository $categoryRepository;

    private int $currentNestingLevel = 1;

    public function __construct(CategoryRepository $categoryRepository)
    {
        $this->categoryRepository = $categoryRepository;
    }

    public function getCategoriesDataByParentCategoryId(int $parentCategoryId): array
    {
        $categories = $this->categoryRepository->getByParentCategoryId($parentCategoryId);
        $categoriesData = [];

        foreach ($categories as $category) {
            $categoriesData[] = $this->getCategoryData($category);
        }

        return $categoriesData;
    }

}

罗伯特·C·马丁(RobertC.Martin)在清洁代码中写道，使用JavaDoc(原文如此！)对于所有方法/变量等都是不好的做法，降低了代码的可读性。此外，他还说，注释( DocBlock )可能并不反映指定元素的当前状态(例如，在DocBlock中我们有int，但是变量被更改为字符串)。

正如我所检查的，PSR标准主要讲的是如何使用DocBlock，以及它们的外观，而不是什么时候应该使用它们。

你觉得这个怎么样？我们应该始终对代码中的所有元素或仅在特定情况下使用DocBlock吗？在这两种情况下，你都看到了什么样的利弊？

Answer 1

Bob叔叔说，这是正确的，是他的书-使用注释，以提供信息，你不能明确地说你的代码。如果注释只是重复函数名和参数，则不需要使用它。正如书中提到的，当代码发生变化时，评论往往保持不变，从而使下一个开发人员陷入困境。

因此，在注释中表示任何特定于域的规则和策略，这些规则和策略不能用函数名和变量表示。

另外，由于清洁代码书主要是围绕Java语法支持编写的--在PHP中，我们不能在代码中显式地声明此方法会抛出异常。这意味着，我们可以通知IDE和开发人员期望异常的唯一方法是使用@块标记。

此外，Java支持注释，而PHP不支持注释。这是对评论的另一种可能的使用。一些框架决定使用类似Symfony的路由注释。带有实体注解等的原则ORM。它们是在库中读取和编译的，以提供类似于构建注释的支持。

因此，按照Bob叔叔在他的书中所建议的那样使用注释，并添加以下由于PHP性质而增加的内容：

• 注释支持(@请参阅
  • 标记中的异常
  • 任何不能用类/函数/变量名称

  表示的逻辑)

还有一种可能的用法是特定于IDE的或特定于工具的注释，如：

给定inspections

• PHPMD的抑制
• PHPStorm给定警告的抑制

正如@El_Vanja指出的那样：

对于预期的类型，可以更具体一些，比如可迭代的内容：@param string[]或@return SomeClass[]