À quoi sert une revue de code
Une revue de code, c’est un collègue qui lit votre modification avant qu’elle rejoigne le code principal. Elle attrape des fautes que vous ne voyez pas dans votre propre travail, et elle répand la connaissance du code dans l’équipe.
Une bonne revue s’apprend. Elle regarde ce que fait la modification, pas seulement son aspect.
À la fin de cette leçon
Remarque
Je peux lire une petite modification, trouver ce qui ne va pas en la lançant, et écrire un commentaire utile.
Mots clés
| Mot | Ce que ça veut dire |
|---|---|
| Diff | la liste des lignes qu’une modification retire et ajoute |
| Revue de code | un collègue lit une modification avant qu’elle soit fusionnée |
| Cas limite | une entrée inhabituelle, comme une liste vide, que le code doit quand même gérer |
| Commentaire de revue | une note sur un endroit de la modification, qui dit quoi regarder de nouveau |
| Reste | ce qu’un développeur a oublié de retirer, comme un print de débogage |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Une modification à relire
Un collègue veut ranger une petite fonction. Elle fait la moyenne des notes que les clients ont données à un produit. Créez deux dossiers : avant contient le code d’aujourd’hui, et apres contient le code avec sa modification.
Votre travail est de la relire, comme sur une demande de fusion.
Créer les deux dossiers
mkdir -p ~/revue/avant ~/revue/apresAffichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Entrer dans le projet
cd ~/revueAffichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Écrire le code d’aujourd’hui
printf 'def moyenne_notes(notes):\n if len(notes) == 0:\n return 0.0\n total = 0\n for note in notes:\n total = total + note\n return total / len(notes)\n' > avant/notes.pyAffichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Écrire la version du collègue
printf 'def moyenne_notes(notes):\n print("notes", notes)\n return round(sum(notes) / len(notes), 1)\n' > apres/notes.pyAffichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Lire le diff avant tout le reste
Un diff montre seulement ce qui a changé. Une ligne qui commence par - a été retirée. Une ligne qui commence par + a été ajoutée. Une ligne qui commence par une espace est du contexte, laissé tel quel.
La ligne @@ dit où se trouve le changement. Ici, l’ancien fichier va de la ligne 1 sur 7 lignes, et le nouveau de la ligne 1 sur 3.
Montrer la modification sous forme de diff
diff -u avant/notes.py apres/notes.py | tail -n +3Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Poser quatre questions à chaque modification
Fait-elle ce qu’elle dit ? Ici, elle dit qu’elle range la fonction.
Que se passe-t-il aux limites : une liste vide, un seul élément, une très grande liste ? Un test le remarquerait-il ? Reste-t-il quelque chose en trop ou de flou, comme une ligne de débogage ou un nom vague ?
Lancer la modification, ne pas seulement la lire
La lecture montre ce qui semble faux. Le lancement montre ce qui est faux. Essayez les mêmes appels sur les deux versions, y compris la liste vide. PYTHONPATH indique à Python quel dossier importer.
Essayer l’ancien code
PYTHONPATH=avant python3 -B -c "from notes import moyenne_notes; print(moyenne_notes([4, 5]), moyenne_notes([]))"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Essayer le nouveau code sur deux notes
PYTHONPATH=apres python3 -B -c "from notes import moyenne_notes; print(moyenne_notes([4, 5]))"Affichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Essayer le nouveau code sur une liste vide
PYTHONPATH=apres python3 -B -c "from notes import moyenne_notes; print(moyenne_notes([]))" 2>&1 | grep ErrorAffichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Chercher les restes dans le nouveau code
grep -n "print(" apres/notes.pyAffichée ici, non exécutée. Créez un compte gratuit pour appuyer sur Exécuter et la saisir dans le terminal de votre propre labo.
Écrire un commentaire qui aide
Un commentaire utile nomme l’endroit, dit ce que vous avez vu, dit pourquoi c’est important et propose une suite. Il parle du code, pas de la personne.
Un commentaire qui dit seulement « mauvais » ou « à corriger » ne donne rien à l’auteur pour agir.
Exemple travaillé : commentaires faibles et utiles
| Commentaire faible | Commentaire utile |
|---|---|
| C’est faux | Ligne 1 : moyenne_notes([]) lève maintenant ZeroDivisionError. L’ancien code rendait 0.0. Peut-on garder ce cas et ajouter un test ? |
| Enlève ça | Ligne 2 : ce print écrira dans les journaux à chaque appel. Est-il resté du débogage ? |
| Pourquoi arrondir ? | Ligne 3 : arrondir à une décimale change 4,33 en 4,3 pour tous les appelants. Est-ce voulu ? Si oui, dites-le dans le nom ou le titre. |
| Il faut des tests | Aucun test n’a changé. Un test pour la liste vide et un pour une seule note protégeraient la prochaine modification. |
Les cellules que les étudiants remplissent restent vides dans cet aperçu.
Une erreur fréquente
Attention
Beaucoup de relecteurs ne vérifient que les noms et les espaces, puis approuvent. Le style compte le moins. Lancez la modification, essayez le cas vide, et demandez-vous si un test remarquerait la casse.
Pour aller plus loin : relire votre propre changement
Faites une petite modification à l’une de vos fonctions, comme l’ajout d’une option. Copiez d’abord l’ancien fichier.
Lancez diff -u sur les deux, puis répondez aux quatre questions comme un relecteur. Écrivez un commentaire que vous seriez heureux de recevoir.