Rédiger ses commentaires de revue de code avec la dictée vocale

Un commentaire de revue de code utile ne se contente pas de signaler ce qui semble incorrect. Il décrit le comportement, explique son importance et indique la suite attendue. Saisir ces explications à répétition peut couper le fil de la revue. À l'inverse, une note comme « gérer le cas vide » laisse souvent trop de questions ouvertes.

La dictée vocale permet de rédiger l'explication tant que le raisonnement est encore frais. Sur votre Mac, gardez les différences de code visibles, ouvrez un brouillon de commentaire et expliquez le problème comme à un collègue. Relisez ensuite le texte avant de le publier. La dictée retranscrit votre explication ; elle ne vérifie pas le code et ne détermine pas si la modification est correcte.

1. Rassembler les éléments avant de dicter

Limitez chaque commentaire à un seul point. Repérez la ligne ou la fonction concernée, la saisie ou la situation en cause, puis le comportement observé ou attendu. Si vous n'avez pas exécuté le code, précisez que votre doute vient de sa lecture. Un défaut possible ne doit pas être présenté comme un bug reproduit.

Décidez aussi du type de réponse souhaité :

• Modification nécessaire : indiquez le problème concret ou l'exigence convenue à satisfaire avant l'approbation.
• Suggestion : précisez que l'amélioration est facultative.
• Question : demandez du contexte lorsque vous ne savez pas encore si une modification s'impose.

Suivez les conventions de votre équipe. Une préférence personnelle ne devient pas un motif de blocage simplement parce qu'elle est exprimée avec fermeté.

2. Dicter le raisonnement, puis ajouter les références exactes

Procédez en trois temps : « Dans cette situation, j'observe ce comportement. Cela compte parce que voici la conséquence. Pourrait-on effectuer cette modification ou cette vérification ? » Marquez une pause entre les idées et restez sur un seul sujet.

Ajoutez ensuite les identifiants, chemins de fichiers et extraits de code directement depuis la source. Pour du code dont le sens dépend de chaque signe, ne vous fiez pas uniquement à la reconnaissance vocale. Supprimez les répétitions et parlez de l'implémentation et de ses effets, pas de la personne qui l'a écrite.

3. Transformer une note vague en retour exploitable

Voici un exemple fictif dans lequel la personne chargée de la revue a reproduit le comportement en local.

Note initiale : « Il faut corriger le cas de la recherche vide. »

Commentaire retravaillé :

Modification nécessaire — recherche vide : lorsque je lance une recherche contenant uniquement des espaces, la zone de résultats reste en cours de chargement. J'ai reproduit ce comportement en local avec la modification actuelle. L'utilisateur n'obtient ni résultat ni indication sur la marche à suivre.

Pourrait-on traiter les saisies composées uniquement d'espaces avant de lancer la recherche et afficher le message convenu pour une saisie vide ? Merci d'ajouter également un test de ce parcours pour vérifier que l'état de chargement se termine correctement.

Si le problème n'est qu'une hypothèse, commencez par « À la lecture de cette branche, il semble que… » et demandez si un autre parcours couvre déjà ce cas. Si le message à afficher n'a pas été défini, clarifiez le comportement attendu au lieu d'inventer une exigence.

4. Réutiliser un modèle court

Type : [Modification nécessaire / suggestion / question]

Contexte : dans [emplacement ou situation], [comportement observé ou doute explicitement présenté comme tel].

Effet : ce point importe parce que [conséquence précise].

Suite attendue : pourrait-on [modification ciblée, vérification ou explication] ?

Éléments disponibles : [Étapes de reproduction, exigence pertinente ou résultat de test, le cas échéant].

Ces rubriques servent à préparer le commentaire, pas à imposer une structure à chaque réponse. Deux phrases peuvent suffire pour une petite suggestion. Si le sujet concerne plusieurs fichiers, rassemblez-le dans la synthèse de la revue et ajoutez des liens vers les passages utiles plutôt que de répéter le même texte partout.

5. Relire avant de publier

Vérifiez les noms, les négations et les termes techniques à partir des différences de code. Assurez-vous qu'un « fonctionne » n'est pas devenu « ne fonctionne pas » et que les résultats de tests cités existent réellement. Relisez enfin le commentaire du point de vue de son destinataire : sait-il quoi faire sans devoir deviner votre intention ?

Pour compléter ce processus, consultez les guides sur les descriptions de pull requests et les rapports de bug clairs.

TypeFree est un moyen simple de transformer la parole en texte modifiable et d'écrire plus vite. Dictez le raisonnement de votre prochain commentaire de revue de code, vérifiez les détails, puis publiez un retour qui aide à avancer.