How to use DocBlocks in PHP 7.4?

Question

Generaly, using DocBlock in PHP is one of the best practices. It was very usefull for previous versions of PHP (lesser then PHP 7.3 or especially 7.4). It informs developers about class properties types, arguments types expected and values returned by methods (in case of lack of strict typying in PHP).

Lets say in PHP 5.6, code can look like:

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;
    }
}

But these DocBlocks do not provide any additional information in this case, when we use 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. Martin writes in Clean code, that using JavaDoc(sic!) for all methods/variables, etc. is bad practices and decreases code readability. Additionaly, he said it is possible, that comment (DocBlock) does not reflect current state of specified element (e.g. in DocBlock we have int, but variable was changed into string)

As I checked, PSR standards mainly said only, how to use DocBlock and how they should look like, but not when they should be used.

What do you think about this? Should we use DocBlock always for all elements in code or only in specific cases? What kind of pros and cons you see in both cases?

vuryss · Answer 1 · 2020-04-04T21:30:26.100

Uncle Bob said it right is his book - use comments to provide information that you cannot explicitly say with your code. If the comment is just repeating the function name and the parameters - no need to use it. As it's mentioned in the book, the comments tend to stay the same when the code changes leaving the next developer in a bad situation.

So express in comments any domain-specific rules and policies that cannot be expressed with the function names and variables.

Also as the Clean code book is written mainly around Java syntax support - in PHP we cannot state in the code explicitly that this method throws an exception somewhere down the road. That means the only way we can notify the IDEs and the developers to expect exceptions is with the @throws tag.

Also Java supports annotations and PHP does not. This is another possible use of the comments. Some frameworks decided to make use of that - like Symfony with it's routing annotations. Doctrine ORM with Entity annotations and so on. They are read and compiled within the libraries to provide support similar to build in annotations.

So use the comments as uncle Bob recommends in his book, with the following additions due to PHP nature:

Annotation support (@see Doctrine annotations)
@throws tag for Exceptions
Any logic that cannot be expressed with the class/function/variable names

Also a possible usage is IDE-specific or tool-specific comments like:

PHPStorm suppression of given inspections
PHPMD suppression of given warnings

As pointed by @El_Vanja:

You can be more specific for the expected type like the contents of an iterable: @return SomeClass[] or @param string[]

I'd just like to explicitly point out one more case where it can be useful, and that is to specify contents of arrays or iterables, for example `@return int[]` or `@param iterable`, since `array` and `iterable` are hints that are a bit too broad. Even though one could easily refrain from using those if the contents are made clear through property/method names. — El_Vanja, Apr 04 '20 at 21:23

How to use DocBlocks in PHP 7.4?

1 Answers1