Вообще, использование DocBlock в PHP является одной из лучших практик. Это было очень полезно для предыдущих версий 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;
}
}
Но эти DocBlocks не предоставляют никакой дополнительной информации в этом случае, когда мы используем PHP 7.4:
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. Мартин пишет в чистом коде, что использует JavaDo c (si c!) Для всех методов / переменных и т. Д. c. это плохая практика и снижает читабельность кода. Кроме того, он сказал, что возможно, что комментарий (DocBlock) не отражает текущее состояние указанного элемента (например, в DocBlock у нас есть int, но переменная была заменена на строку)
Как я уже проверял, стандарты PSR в основном говорили только как использовать DocBlock и как они должны выглядеть, но не тогда, когда их следует использовать.
Что вы думаете об этом? Должны ли мы использовать DocBlock всегда для всех элементов в коде или только в определенных c случаях? Какие плюсы и минусы вы видите в обоих случаях?