Générateur de commentaires de code
Rédigez les commentaires de code qui méritent d'être gardés : ceux qui expliquent pourquoi une ligne existe, pas ce que fait la syntaxe.
Ce générateur de commentaires de code rédige le genre de note que votre équipe a vraiment envie de retrouver six mois plus tard, celles qui expliquent pourquoi un bout de code existe ou ce qui casse si quelqu'un y touche. Vous collez un extrait ou décrivez ce que fait le code, vous choisissez le langage et le style de commentaire, et nous repérons les passages sensibles : appels réseau, tout ce qui ressemble à de l'authentification, TODO oubliés, nombres magiques et gestion des erreurs. Vous nommez le lecteur futur, le responsable et les faits qui doivent rester vrais, et nous rendons un docblock, une note inline, un commentaire de relecture, une note de configuration ou un TODO avec responsable, plus une ou deux variantes, un score d'utilité et une liste de vérification. Nous ne prétendons jamais que chaque commentaire mérite d'être gardé. Tout tourne dans votre navigateur, rien de ce que vous saisissez n'est envoye.
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
Ce générateur de commentaires de code rédige les commentaires qui méritent d'être gardés, ceux qui expliquent pourquoi un bout de code existe plutôt que de paraphraser la syntaxe ligne par ligne. Vous collez un extrait, ou décrivez simplement ce que fait le code, puis vous choisissez le langage et le style de commentaire. Nous repérons les passages sensibles, appels réseau, authentification, nombres magiques, TODO oubliés, et nous proposons une ou deux formulations à coller telles quelles. Vous récupérez aussi un score d'utilité et une liste de vérification rapide, pour qu'un docblock, une note inline ou un TODO avec responsable arrive en bon état. Tout tourne dans votre navigateur, rien de ce que vous saisissez n'est envoye.
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.