Générateur de commentaires de code
Rédige les commentaires de code qui méritent d'être gardés : ceux qui disent pourquoi un truc existe, pas ce que fait la syntaxe.
Ce générateur de commentaires de code rédige le genre de note que tu as vraiment envie de retrouver six mois plus tard, celles qui expliquent pourquoi un truc est fait comme ça ou ce qui casse si on y touche. Colle un snippet ou décris ce que fait le code, choisis le langage et le style, et il repère les passages sensibles : appels réseau, tout ce qui sent l'auth, TODO traînants, nombres magiques et gestion des erreurs. Tu nommes le lecteur futur et les faits qui doivent rester vrais, puis il te rend un docblock, une note inline, un commentaire de review ou un TODO avec responsable, plus une ou deux alternatives, un score d'utilité et une checklist. Tout tourne dans ton navigateur et rien ne quitte la page.
100% dans votre navigateur. Rien de ce que vous tapez ne quitte cette page.
Rédaction de commentaires, analyse du contexte de code et notes de review
Les commentaires qui se contentent de paraphraser le code ligne par ligne, ça m'a vite lassé. Du coup j'ai construit ça. L'outil rédige le genre de commentaire que j'ai vraiment envie de retrouver six mois plus tard : ceux qui expliquent pourquoi un truc est fait comme ça, ou ce qui casse si on y touche. Colle un snippet, ou décris simplement ce que fait le code. Choisis le langage et le style de commentaire. L'outil repère les passages sensibles, te propose une ou deux formulations, et te rend quelque chose qui mérite d'être collé tel quel. Et au passage, rien ne quitte la page.
Franchement ? Le meilleur commentaire, c'est parfois pas de commentaire du tout. Garde le tien seulement quand il dit quelque chose que les noms ou les tests ne peuvent pas exprimer.
Un bon commentaire explique la raison que le lecteur ne peut pas deviner
Personne ne le dit aux juniors, alors je vais le faire : un commentaire qui traduit le code en français ne vaut rien. Je sais lire une boucle. Et celui qui héritera de mon bazar aussi. Ce qu'aucun de nous ne peut lire, c'est tout ce qui n'est pas dans le fichier. Pourquoi on laisse une erreur visible exprès. Pourquoi ce timeout-là est chouchouté alors que les autres non. Pourquoi une valeur de config qui ressemble à une faute de frappe est en fait essentielle, ou pourquoi ce contournement moche doit rester là tant que l'équipe plateforme n'a pas livré son correctif. Ça, écris-le. Le reste, c'est du bruit.
C'est toute l'idée ici. L'outil pose les questions que je me pose avant d'écrire un commentaire : pourquoi est-ce que ça mérite vraiment d'être dit, qui le lira plus tard, quels faits doivent rester vrais peu importe comment le code va muter. Ensuite il scanne ton snippet et signale ce qui mérite généralement une note. Les appels réseau. Tout ce qui sent l'auth. Les TODO traînants, les nombres magiques, les clés de config, la gestion des erreurs. Il ne prétend pas que chaque commentaire est bon à garder, ce que j'apprécie, parce que les miens ne le sont sûrement pas. Tu obtiens un premier jet correct. C'est tout.
Quand un commentaire mérite d'être gardé
Ma règle perso : un commentaire gagne sa place quand modifier le code sans lui ferait livrer un bug ou ouvrir un trou de sécurité. Un docblock précise ce qu'une fonction attend et comment elle échoue. Une note inline protège cette branche bizarre dont tu auras oublié la raison d'ici vendredi. Un commentaire de review pointe le passage que tu veux faire relire par un collègue. Et une note de config ? C'est ce qui empêche quelqu'un de copier-coller tes valeurs de prod directement en dev, puis de se demander pourquoi tout est en feu.
- Docblock quand une fonction a une intention et des limites qui méritent d'être posées d'emblée, avant que quiconque l'appelle.
- Note inline juste à côté de cette petite décision qui aura l'air complètement fausse tant que tu ne l'expliques pas.
- Commentaire de review quand la suite, c'est une discussion dans la PR, pas une ligne dans le source.
- Note de configuration pour les histoires d'env et de feature flags qui te mordent dès que tu changes de machine.
- TODO avec responsable qui ne vaut absolument rien tant qu'il ne nomme pas qui va s'en occuper, et pourquoi.
Comment éviter les commentaires qui pourrissent
Commence par les corrections ennuyeuses. Renomme la variable. Découpe la fonction. Écris un test, peut-être. Neuf fois sur dix le besoin de commentaire s'évapore tout seul, et honnêtement je trouve que la plupart des commentaires sont un code smell déguisé, même si je suis peut-être en train de me convaincre tout seul. S'il reste vraiment quelque chose d'unique, fais court. Ne décris pas l'implémentation : c'est précisément ce que le prochain refactor va changer, et là ton commentaire ment tranquillement aux gens. Accroche-le plutôt à une raison. Un contrat, une limitation, un système externe qui déraille les soirs de pleine lune, un bug contre lequel tu te protèges. Et si tu peux, note quand ce commentaire cesse d'être vrai, pour que le suivant sache quand le supprimer.
Exemples concrets
Quelques-uns tirés de mon propre code. Un vérificateur d'en-têtes de sécurité a besoin d'un commentaire pour que personne plus tard ne « simplifie » un appel réseau échoué en une jolie coche verte. Un webhook de facturation a besoin d'une note sur l'idempotence, parce que les événements en double, ce n'est pas un bug. C'est le quotidien. Un override CSS bien tordu mérite une ligne nommant le bug navigateur qu'il rustine. Et un filtre SQL devrait expliquer la règle métier derrière la condition, pas annoncer que oui, il y a bien une clause WHERE. Le WHERE, je le vois.
Questions fréquentes
Qu'est-ce qui fait un bon commentaire de code ?
Il répond au pourquoi, jamais au quoi. Le quoi, le code le couvre déjà, juste là sous tes yeux. Ce qu'il ne peut pas montrer, c'est l'intention, ou le piège qui mordra le suivant à 2h du matin. C'est ça qui mérite une phrase.
Est-ce que chaque fonction devrait avoir un docblock ?
Non. Une petite fonction au nom clair et sans aucune surprise n'a pas besoin d'un paragraphe de cérémonie boulonné par-dessus. Je réserve les docblocks aux fonctions dont le contrat ou un piège opérationnel comptent vraiment pour celui qui les appelle. Le reste peut parler de lui-même.
Les commentaires TODO, c'est mal ?
Seulement les vagues. Un simple TODO à corriger est un aveu sans le moindre plan. Un bon TODO nomme qui est sur le coup et ce qui doit arriver avant qu'il puisse partir. C'est toute la différence entre un rappel et un graffiti.
Est-ce que les commentaires peuvent remplacer les tests ?
Aucune chance. Un commentaire te dit ce que quelqu'un avait l'intention de faire. Un test te dit ce que le code fait vraiment, là, maintenant, aujourd'hui. L'un raconte une histoire. L'autre est une preuve. Les codebases auxquelles je fais confiance s'appuient sur les deux, parce qu'ils répondent à des questions complètement différentes.