New in Symplify 3: DocBlock Cleaner Fixer

Found a typo? Edit me
This post is deprecated since March 2019. Its knowledge is old and should not be used.

This fixer was deprecated and removed in EasyCodingStandard 6. Use official NoSuperfluousPhpdocTagsFixer instead.

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 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 Config

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symplify\CodingStandard\Fixer\Commenting\RemoveEmptyDocBlockFixer;
use Symplify\CodingStandard\Fixer\Commenting\RemoveSuperfluousDocBlockWhitespaceFixer;
use Symplify\CodingStandard\Fixer\Commenting\RemoveUselessDocBlockFixer;

return function (ContainerConfigurator $containerConfigurator): void {
    $services = $containerConfigurator->services();




3. Run It

vendor/bin/ecs check src

4. See the Diff

5. And Fix It

vendor/bin/ecs check src --fix

Happy eye resting!

Have you find this post useful? Do you want more?

Follow me on Twitter, RSS or support me on GitHub Sponsors.