Formations — 1 037 leçons en français

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.

Lire l'explication détaillée et faire le quiz →

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.