Accueil › Git & CI/CD › L'art du commentaire utile
L'art du commentaire utile
La revue de codeintermediaire
Un commentaire de revue réussit s'il produit une action claire. Il échoue s'il produit une question, une justification, ou du silence.
Les trois ingrédients
1. Le fait observable — « cette fonction renvoie null quand le compte
est supprimé »
2. La conséquence — « et l'appelant ligne 42 déréférence le résultat »
3. Le niveau — « bloquant » / « suggestion » / « question »
Un commentaire qui contient les trois se traite sans aller-retour. Un commentaire qui n'en contient aucun — « ça ne va pas » — en demande deux avant même de commencer.
Dire ce que fait le code, pas ce que la personne a fait
⛔ « Tu as oublié de gérer le cas nul. »
✅ « `trouverClient` renvoie `null` pour un compte supprimé ; ici le résultat
est déréférencé directement. »
Ce n'est pas une question de politesse. La seconde formulation est vérifiable : elle désigne un comportement que l'auteur peut constater ou réfuter. La première oblige à se défendre.
La suggestion applicable
Les forges acceptent un bloc de suggestion que l'auteur applique d'un clic :
```suggestion
if (!client) return null;
```
Trois mots de contexte au-dessus, la suggestion en dessous. L'aller-retour devient une seconde.
Les termes à connaître
- Commentaire bloquant
Remarque qui doit être traitée avant la fusion. Elle porte sur le comportement, la sécurité ou la correction — jamais sur une préférence.
- Commentaire préfixé
Convention d'équipe marquant la portée d'une remarque : « bloquant », « suggestion », « question », « détail ». Elle dit à l'auteur ce qu'il doit faire, sans l'obliger à deviner.
- Suggestion de code
Bloc proposé dans un commentaire que l'auteur applique d'un clic sur la forge. Transforme un aller-retour en une seconde.
- Fil de discussion
Commentaire et ses réponses, ancré sur une ligne du diff. Il se résout — le résoudre signifie « traité », pas « j'ai lu ».
- Revue en direct
Relecture faite ensemble, de vive voix. Sort du blocage quand un fil de discussion dépasse quelques allers-retours sans converger.
- Critique du code, pas de l'auteur
Formuler la remarque sur ce que fait le code plutôt que sur ce que la personne a fait. Ce n'est pas une politesse : « cette fonction renvoie null » est vérifiable, « tu as oublié » ne l'est pas.
Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.