php - 如何在 PHP 7.4 中使用 DocBlocks？

Question

通常，在 PHP 中使用 DocBlock 是最佳实践之一。它对于以前版本的 PHP(低于 PHP 7.3，尤其是 7.4)非常有用。它通知开发人员有关类属性类型、期望的参数类型和方法返回的值(在 PHP 中缺乏严格类型的情况下)。

假设在 PHP 5.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;
    }
}

但是在这种情况下，当我们使用 PHP 7.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;
    }

}

Robert C. Martin 在 Clean code 中写道，对所有方法/变量等使用 JavaDoc(原文如此!)是不好的做法，会降低代码的可读性。此外，他说，注释 (DocBlock) 可能不会反射(reflect)指定元素的当前状态(例如，在 DocBlock 中我们有 int，但变量已更改为字符串)

我查了一下，PSR标准主要只是说了，如何使用DocBlock以及它们应该是什么样子，而没有说什么时候应该使用。

你怎么看这件事？我们应该始终对代码中的所有元素使用 DocBlock 还是仅在特定情况下使用 DocBlock？您在这两种情况下看到了什么样的利弊？

Answer 1

Bob 大叔在他的书中说的很对——使用注释来提供您无法在代码中明确表达的信息。如果注释只是重复函数名称和参数 - 则无需使用它。正如书中提到的那样，当代码发生变化而使下一位开发人员陷入困境时，注释往往会保持不变。

因此，在注释中表达任何无法用函数名称和变量表达的特定于域的规则和策略。

此外，由于 Clean 代码书主要围绕 Java 语法支持编写 - 在 PHP 中，我们无法在代码中明确声明此方法会在某处抛出异常。这意味着我们可以通知 IDE 和开发人员预期异常的唯一方法是使用 @throws 标记。

此外，Java 支持注解，而 PHP 不支持。这是注释的另一种可能用途。一些框架决定利用它——比如 Symfony 及其路由注释。 Doctrine ORM with Entity annotations 等等。它们在库中被读取和编译，以提供类似于内置注释的支持。

所以使用 Bob 叔叔在他的书中推荐的评论，由于 PHP 的性质，添加以下内容:

• 注释支持(@see Doctrine 注释)
• @throws 异常标记
• 任何不能用类/函数/变量名表达的逻辑

另外一种可能的用法是特定于 IDE 或特定于工具的注释，例如:

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

正如@El_Vanja 所指出的:

• 您可以更具体地指定预期类型，例如可迭代对象的内容:@return SomeClass[] 或 @param string[]