Sans commentaire

Je ne compte plus les fois où je remarque ce genre de structure :

class EmailEventManager
{
    /**
     * EmailEventManager constructor.
     * @param EntityManagerInterface $entityManager
     * @param EmailManager $emailManager
     */
    public function __construct(
        private EntityManagerInterface $entityManager,
        private EmailManager $emailManager,
        private Registry $workflows
    ) {}

    // …
}

Que ce soit clair : je n’ai pas inventé ce code pour les besoins de ce post. Il provient d’une pull request récente sur un projet en activité. Et ce n’est qu’un des innombrables exemples que j’aurais pu choisir.

Ces blocs de commentaires (DocBlock) me hérissent le poil. En l’occurrence :

• le résumé (summary) ne donne aucune information que le code ne donne pas déjà,
• les tags @param dupliquent la signature de la fonction, mais sans offrir aucune garantie sur le type des arguments — contrairement au code,
• le bloc de commentaires est incomplet : le paramètre $workflows n’y est pas présent.

Nous violons donc allégrement deux des neuf règles à suivre pour des commentaires utiles :

• Comments should not duplicate the code.
• Comments should dispel confusion, not cause it.

Comme le mentionne également l’article lié ci-dessus (je vous conseille grandement sa lecture), les commentaires sont coûteux à maintenir. Si $workflows n’y apparaît pas, c’est certainement qu’il a été ajouté après génération du bloc. Ou alors le bloc a été copié d’une autre classe, et laissé tel quel. Ce code n’est même pas en production, et il est déjà obsolète. Et cette obsolescence va empirer, causant de plus en plus de confusion.

On est donc face à des commentaires qui sont au mieux inutiles et toujours nuisibles. Pourtant, un déprimant pourcentage de développeurs va les ajouter de toute façon. Pire, ils vont même refuser leur suppression.

Pourquoi ?

N’en faites pas partie. S’il vous plaît.

Mais le projet ne définit aucun style de programmation !

Admettons que vous ayez besoin d’un style de programmation pour ça (🙄). La règle no_superfluous_phpdoc_tags de PHP CS Fixer supprimera toutes les annotations @var, @param et @return inutiles. Cependant le plus efficace reste de ne pas les ajouter…

Mais mon IDE ajoute les DocBlocks automatiquement !

S’il est impensable de perdre du temps à les supprimer (🙄), alors configurer ledit IDE est probablement la solution logique.

Par exemple, les utilisateurs de PhpStorm pourront se rendre dans l’onglet « Code » de File and Code Templates et supprimer les DocBlocks des templates PHP.

Si vous connaissez la technique pour d’autres IDEs, vous pouvez ouvrir une pull request pour les voir mentionnées ici. Sans commentaires inutiles bien entendu !