C'est une remarque ou un reproche ?
En revue de code, le ton se perd. Une même phrase peut être reçue comme un coup de main ou comme une pique, selon l'état d'esprit de la personne qui la lit. Conventional Comments apporte une réponse presque naïve à ce problème : chaque commentaire commence par dire ce qu'il est.
Ce nom de variable ne veut rien dire.
Sec. Sans intonation, sans visage. Lu un vendredi soir après deux jours passés sur la PR, ça peut facilement sonner comme : tu bâcles.
nitpick (non-blocking): ce nom de variable ne veut rien dire
Exactement les mêmes mots. Mais nitpick, c'est le relecteur qui précise lui-même : « je sais, c'est un détail ». La pique disparaît, sans qu'on ait adouci le fond.
Une revue de code, c'est du texte. Rien que du texte.
Pas de haussement d'épaules. Pas de sourire en coin. Pas de « je réfléchis à voix haute ». Deux personnes, deux écrans, souvent deux fuseaux horaires et parfois deux langues maternelles. Tous les indices qui, à l'oral, permettent de comprendre le poids d'une remarque ont disparu. Il ne reste que les mots.
Le relecteur était pressé, alors il a fait court. L'auteur lit de la froideur là où il n'y avait que de la concision.
« Cette boucle pourrait être plus simple. » Une exigence ou une simple idée ? L'auteur n'en sait rien. Dans le doute, il réécrit la boucle. Deux heures perdues.
Un développeur junior reçoit quinze commentaires. Il ne voit pas quinze remarques distinctes. Il voit quinze fois : « tu ne sais pas faire ». Douze ne sont que des détails. Un seul compte vraiment.
Un relecteur qui ne veut blesser personne met toutes ses remarques au conditionnel. Plus rien ne paraît important. La revue devient polie, vague et inutile.
Aucun de ces malentendus ne vient d'un désaccord technique. Ils ont tous la même cause : l'intention du relecteur n'apparaît nulle part.
Chaque commentaire dit d'abord ce qu'il est.
Conventional Comments est une convention publiée sur conventionalcomments.org. Le principe tient en une ligne : chaque commentaire commence par un mot qui indique la nature de la remarque. On peut ensuite préciser, entre parenthèses, si elle est bloquante.
nature (bloquant ou non): ce que vous avez à dire
| Ce que le relecteur écrit | Ce que l'auteur comprend |
|---|---|
| praise: la gestion d'erreur est très lisible | Quelqu'un a pris le temps de signaler ce qui fonctionne bien. |
| nitpick: ce nom pourrait être plus court | C'est mineur — et le relecteur le dit lui-même. |
| question: pourquoi un timeout à 30 s ? | On me pose une question. On ne m'accuse de rien. |
| suggestion (non-blocking): on pourrait extraire une méthode | Une idée, pas une consigne. À moi de décider. |
| issue (blocking): le jeton de session n'est jamais invalidé | C'est sérieux — et au moins, c'est clairement annoncé. |
Le label ne change pas votre message. Il donne la clé pour le lire.
C'est ce qui distingue Conventional Comments des conseils habituels sur la « bienveillance en revue ». Personne ne vous demande d'enrober vos phrases, d'ajouter des émojis ou de commencer par un compliment. Vous écrivez ce que vous aviez à dire. Vous ajoutez simplement devant le mot qui rend votre intention explicite.
L'effort repose sur le relecteur, pas sur celui qui reçoit le commentaire.
C'est un aspect qu'on ne remarque pas forcément tout de suite. Choisir un label oblige le relecteur à s'arrêter une seconde et à se demander ce qu'il est réellement en train de faire. Et cette seconde suffit souvent à désamorcer la remarque avant même qu'elle soit lue.
Écrire nitpick devant sa propre remarque, c'est reconnaître soi-même : « c'est un détail ». Le relecteur désamorce son commentaire avant qu'il arrive à l'auteur.
On pense rarement à signaler spontanément ce qui est bien fait. Un bouton dans une barre d'outils, lui, vous y fait penser. Le mécanisme est tout simple, mais il change l'ambiance d'une revue.
Marquer un point comme bloquant, c'est assumer qu'il l'est. Fini le « bon, je te laisse voir », qui n'engage personne et laisse l'auteur seul avec le doute.
Clore un point sans agir oblige à expliquer pourquoi. Un désaccord ne peut plus simplement disparaître en silence.
« Ça va rendre les revues trop molles. »
C'est l'inverse. Sans convention, le relecteur qui ne veut blesser personne finit par entourer toutes ses remarques de précautions : « Je me demandais si éventuellement on ne pourrait pas peut-être… » À force, plus rien ne paraît vraiment important et le problème sérieux se perd au milieu des précautions.
Avec un label, on peut être direct sans être agressif. issue (blocking): fuite mémoire dans le handler Ce n'est pas un jugement sur la personne qui a écrit le code. C'est une catégorie. La franchise devient plus facile précisément parce que l'intention est explicite.
Sans labels, la même revue s'affiche simplement comme : « 15 commentaires ». Rien de plus. C'est ce chiffre, pris isolément, qui peut décourager un junior — pas les remarques elles-mêmes.
Une bonne habitude se perd vite.
C'est exactement là qu'intervient l'outil — et pas ailleurs. Il n'apprend à personne comment se comporter. Il aide simplement l'équipe à garder le réflexe une fois que plus personne n'y pense consciemment.
Une extension qui écrit pour vous
Une rangée de boutons apparaît au-dessus du champ de commentaire sur GitHub. Tapez ?n et l'extension insère nitpick:. Survolez un bouton et elle vous rappelle à quoi sert le label correspondant. Choisir le bon label devient presque sans effort — et c'est précisément ce qui permet au réflexe de durer.
Les points bloquants restent visibles
L'extension suit les commentaires bloquants non résolus directement sur la pull request et affiche combien il en reste. Plus besoin de parcourir toute la discussion pour vérifier qu'aucun point important n'a été oublié.
L'objectif n'est pas de faire la police. C'est un pense-bête : un point important ne se perd plus au milieu du fil de discussion.
Pour commencer, l'extension suffit à elle seule. La convention, elle, n'a besoin d'aucun outil. Les outils servent uniquement à la rendre plus facile à appliquer dans la durée.
Assist et warn sont disponibles aujourd'hui. Enforce viendra ensuite.
L'extension couvre déjà les deux premières étapes. Enforce ajoutera à terme un contrôle de fusion exécuté au niveau de la plateforme et indépendant du navigateur. Cette capacité fait partie de la feuille de route.
Comment l'adopter en équipeVos commentaires ne quittent jamais votre navigateur.
Ce qu'on écrit en revue de code peut être plus sensible que le code lui-même. L'extension lit et vérifie tout localement. Rien n'est envoyé. Pas de télémétrie. Pas de compte. Aucun token stocké. Elle ne s'exécute que sur les domaines que vous avez explicitement autorisés — github.com compris — et nulle part ailleurs.
Une seule exception : vos propres réglages — comme la langue ou les raccourcis — peuvent être synchronisés par votre navigateur si vous avez activé cette fonction. Des réglages uniquement. Jamais le contenu de vos revues.
Enterprise Cloud · EMU
Enterprise Server
Server (auto-hébergé)
avec des limitations documentées
Firefox
Open source · Apache-2.0
Commencez par un label devant une phrase.
C'est tout. Le reste — l'extension et ses réglages — n'existe que pour vous aider à garder ce réflexe.