New in Symplify 3: DocBlock Cleaner Fixer

Focus on docblock has increased thanks to PHP 7 scalar types and PHPStan with intersection and union types. Thanks to that, more and more docblocks become just visual noise causing cognitive overload.

Symplify 3 introduces a new help hand - fixer that cleans doc block noise for you and makes your code more valuable to the reader.
...when you program, you have to think about how someone will read your code, not just how a computer will interpret it.
Kent Beck, creator of the Extreme Programming and Test Driven Development


Do you find similar patterns in your code?


/**
 * @param string $name
 */
public function addVisitor(string $name)
{
    // ...
}


/**
 * @param InputInterface $input An Input instance
 */
public function getArguments(InputInterface $input)
{
    // ...
}


/**
 * @param array $items
 */
public function prependItems(array $items)
{
    // ...
}


/**
 * @return boolean
 */
public function getStorage(): bool
{
    // ...
}


Do you know what do they have in common? They only duplicate the typehint information and bring no extra value to the reader.

No big deal you might say as code author. But your code is much more read that written, so making it as readable as possible should be your priority.


How to Remove Manually Automatically?

Cleaning every single case would be crazy. Luckily, we live in CLI-refactoring generation, so all we need is new Fixer from Symplify\CodingStandard 3.0 - Symplify\CodingStandard\Fixer\Commenting\RemoveUselessDocBlockFixer.

See pull-request #427

This fixer scans docs blocks, compares it with code types, evaluates value of each one (like you would do) and drops those, which do not add any extra value and only slow down the code reading time.

Tested on many Open-Source Projects

Docblocks don't have any standard format, so I first tested this Fixer on handful of PHP open-source projects. Open them to see, what this fixer can do in real code:

Thanks to that Fixer now covers dozens of edge cases.

Challenge Your Code

1. Install

composer require symplify/easy-coding-standard --dev

2. Create easy-coding-standard.neon

# easy-coding-standard
checkers:
    - Symplify\CodingStandard\Fixer\Commenting\RemoveUselessDocBlockFixer

    # works best with these checkers, to remove empty docblock
    - Symplify\CodingStandard\Fixer\Commenting\RemoveSuperfluousDocBlockWhitespaceFixer
    - Symplify\CodingStandard\Fixer\Commenting\RemoveEmptyDocBlockFixer

3. Run it

vendor/bin/ecs check src

4. See the diff

5. And fix it

vendor/bin/ecs check src --fix


Don't you like mixed or object? The fixer is configurable, so you can set types that you'd like to remove.

# easy-coding-standard.neon
checkers:
    Symplify\CodingStandard\Fixer\Commenting\RemoveUselessDocBlockFixer:
        useless_types: ['mixed', 'object'] # [] by default


Happy eye resting!



What do you think?