如何在PHP7.4中使用DocBlocks？

通常，在PHP中使用DocBlock是最佳实践之一。 它对于PHP的早期版本非常有用，而不是PHP7.3，尤其是PHP7.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时，这些Docblock不提供任何附加信息：

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用干净的代码编写，使用JavaDocsic！对于所有方法/变量等，都是错误的做法，并降低了代码的可读性。 此外，他说，注释DocBlock可能不反映指定元素的当前状态，例如，在DocBlock中，我们有int，但变量被更改为字符串

正如我所检查的，PSR标准主要只是说明如何使用DocBlock以及它们应该是什么样子，而不是何时应该使用它们

---

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

鲍勃叔叔说他的书是对的——使用注释来提供代码中无法明确说明的信息。 如果注释只是重复函数名和参数，则无需使用它。正如书中所提到的，当代码更改导致下一个开发人员处于糟糕的情况时，注释往往保持不变

所以，请在注释中表示不能用函数名和变量表示的任何特定于域的规则和策略

另外，由于干净的代码书主要围绕Java语法支持编写——在PHP中，我们无法在代码中明确说明此方法会在某个地方引发异常。这意味着我们通知IDE和开发人员期望异常的唯一方法是使用@throws标记

Java也支持注释，而PHP不支持。这是评论的另一种可能用法。一些框架决定利用它，比如Symfony和它的路由注释。具有实体注释等功能的ORM。它们在库中读取和编译，以提供类似于内置注释的支持

因此，使用Bob叔叔在书中推荐的注释，并根据PHP的特性添加以下内容：

注释支持@参见条令注释 @抛出异常的标记 不能用类/函数/变量名表示的任何逻辑 还有一种可能的用法是特定于IDE或特定于工具的注释，如：

给定检查的PHPStorm抑制 给定警告的PHPMD抑制 正如@El_Vanja所指出的：

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

---

Bob叔叔说他的书是正确的——使用注释来提供代码无法明确说明的信息。 如果注释只是重复函数名和参数，则无需使用它。正如书中所提到的，当代码更改导致下一个开发人员处于糟糕的情况时，注释往往保持不变

所以，请在注释中表示不能用函数名和变量表示的任何特定于域的规则和策略

另外，由于干净的代码书主要围绕Java语法支持编写——在PHP中，我们无法在代码中明确说明此方法会在某个地方引发异常。这意味着我们通知IDE和开发人员期望异常的唯一方法是使用@throws标记

Java也支持注释，而PHP不支持。这是评论的另一种可能用法。一些框架决定利用它，比如Symfony和它的路由注释。具有实体注释等功能的ORM。它们在库中读取和编译，以提供类似于内置注释的支持

因此，使用Bob叔叔在书中推荐的注释，并根据PHP的特性添加以下内容：

注释支持@参见条令注释 @抛出异常的标记 不能用类/函数/变量名表示的任何逻辑 还有一种可能的用法是特定于IDE或特定于工具的注释，如：

给定检查的PHPStorm抑制 给定警告的PHPMD抑制 正如@El_Vanja所指出的：

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

---

我只想明确指出另一种可能有用的情况，那就是指定数组或iterable的内容，例如@return int[]或@param iterable，因为数组和iterable是有点太宽的提示。即使通过属性/方法名可以很容易地避免使用它们，但我只想明确指出另一个有用的情况，那就是指定数组或iterables的内容 ，例如@return int[]或@param iterable，因为数组和iterable是有点太宽的提示。即使在通过属性/方法名称明确内容的情况下，也可以很容易地避免使用它们。