100% agree. Comments that do nothing but repeat what the code already
says serve no purpose¹. I regularly remove these but can't when it
means PHPCS starts complaining.
Typical example:
/**
* @param User $user
* @param array $rights
* @return bool
*/
public function isAllowed( User $user, array $rights ): bool {
A comment like this does not even qualify as "documentation", I would
argue. It does not contain any information. It's just a copy of the
code.
¹ Ok, it can have a purpose: It marks the code as "this is all we have
to say", similar to @inheritDoc. And it's easier to add actual
documentation when there is already some scaffolding. On the other
hand, all IDEs can auto-generate this when it's needed.
I wanted to update the relevant PHPCS rules for a long time but never
managed to. The idea is relatively simple: When everything in a method
signature does have a type (all parameters as well as a return type)
then no sniff should complain about "missing" documentation. Same for
class properties.
Later we could even _remove_ comments that don't have any additional
information.
Best
Thiemo
_______________________________________________
Wikitech-l mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/
