New in Symplify 3: DocBlock Cleaner Fixer

2 min

Sun, Dec 17, 2017

X comments

Edit Post

This post is deprecated at March 2019 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.





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

<?php // ecs.php declare(strict_types=1); 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 static function (ContainerConfigurator $containerConfigurator): void { $services = $containerConfigurator->services(); $services->set(RemoveUselessDocBlockFixer::class); $services->set(RemoveSuperfluousDocBlockWhitespaceFixer::class); $services->set(RemoveEmptyDocBlockFixer::class); };

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!