2

一般来说，在 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(sic!) 是不好的做法，并且会降低代码的可读性。另外，他说有可能，注释（DocBlock）不反映指定元素的当前状态（例如，在 DocBlock 中我们有 int，但变量已更改为字符串）

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

你怎么看待这件事？我们应该始终对代码中的所有元素使用 DocBlock 还是仅在特定情况下使用 DocBlock？您在这两种情况下都看到了哪些优点和缺点？

4

1 回答 1

5

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

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

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

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

因此，请使用 Bob 叔叔在他的书中推荐的评论，由于 PHP 的性质，添加了以下内容：

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

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

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

正如@El_Vanja 所指出的：

  • 您可以更具体地了解预期类型，例如可迭代的内容：@return SomeClass[]或@param string[]
于 2020-04-04T21:18:42.460 回答