Examiner les différences
- Leçon 7
- 45 min
- Module 3 : Réviser le travail généré
Où nous en sommes
Dans le module 2, nous avons écrit des tâches qu'un assistant peut terminer et vérifier. Maintenant, sa modification pour la fonctionnalité arrive, et ses tests réussissent. Mais des tests réussis ne montrent pas les modifications non demandées, les promesses modifiées ni les suppositions sur les entrées. Dans cette leçon, nous révisons les différences ligne par ligne avec une liste de vérification avant de les accepter, comme un nouveau robinet qu'on vérifie avant de payer le plombier.
Leçon 7 sur 15 · Développement logiciel assisté par l'IAExaminer les différences
1. Mettre en place un environnement de travail sûr
2. Rédiger des tâches exploitables
3. Réviser le travail généré
4. Déboguer et tester avec l'assistant
5. Livrer un travail facile à maintenir
Ce que vous saurez faire
Lisez une modification ligne par ligne avant de l’accepter. Cherchez ce que les tests ne montrent pas : modifications non demandées, promesses modifiées, suppositions sur les entrées et code difficile à maintenir. Des tests réussis sont une preuve parmi d’autres, pas une révision.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
- L’énoncé de tâche et ses critères d’acceptation, dans Problème et critères d’acceptation.
- Comment lire
git diffetgit diff --stat, dans Lire et réviser les différences, du cours L’essentiel de Git et du développement en équipe. - Ce qu’une fonction promet, dans Le contrat d’une fonction, du cours Python pour l’ingénierie de l’IA en pratique.
Ce qu’il vous faut sur votre ordinateur
- Le projet
~/projects/ticket-cleaner-assistdu module 2, sur la branchefeature/category-option, avec son environnement activé.python -m pytestaffiche26 passed(26 tests réussis), etgit statusindiqueworking tree clean(répertoire de travail propre). - Le dossier de laboratoires
~/projects/nextia-learning-labs, avecC15/candidates/. - Si le projet manque ou ne fonctionne plus, suivez les étapes de réinitialisation de Contexte et limites avec l’instantané
end-of-m02. - Aucun compte, aucune clé et aucuns frais. Les modifications que vous révisez proviennent de sessions enregistrées.
Un nouveau robinet, avant de payer
Section intitulée « Un nouveau robinet, avant de payer »Un plombier installe un nouveau robinet de cuisine. À votre retour, vous l’ouvrez, et l’eau coule. Est-ce que vous payez?
Regardez d’abord de plus près. Le plombier a aussi déplacé l’interrupteur, « parce qu’il gênait ». Le nouveau robinet ne donne que de l’eau froide, car le plombier a supposé que vous le vouliez ainsi. Un tuyau sous l’évier a maintenant un raccord que personne ne peut atteindre. L’eau coule, mais le travail n’est toujours pas correct.
L’eau qui coule ressemble à un test réussi. Cela montre qu’une chose fonctionne. Cela ne montre pas ce qui a changé ailleurs, ni ce que le plombier a supposé.
Le problème : « les tests passent, fusionnez »
Section intitulée « Le problème : « les tests passent, fusionnez » »Dans Problème et critères d’acceptation, l’équipe du cours a décrit la fonctionnalité de Grace à un assistant en une phrase. C’était « Ajoutez un moyen de filtrer le rapport par catégorie. » La modification reçue se trouve dans le dossier de laboratoires sous le nom candidat A. Elle est réelle, provient de la session enregistrée feature-vague, et personne ne l’a retouchée.
Dans l’enregistrement, tous ses tests réussissaient : 29 passed (29 tests réussis). Cela plaît à Tomás :
« Les tests passent, et les différences sont petites : 77 lignes. Fusionnez. »
Mais vous savez, depuis le module 2, que le candidat A échoue à 4 des 8 vérifications d’acceptation. Il accepte une seule catégorie, exige l’orthographe exacte et ajoute une clé à chaque rapport. Les tests réussissaient parce que l’assistant les avait écrits pour ses propres décisions. Avant ses modifications, il avait même annoncé ce qu’il ferait :
I’ll add an optional `--category` argument that matches a report category exactly and combines with the status filter. Without it, reports will still include all categories.La deuxième phrase semble dire « le rapport ne change pas », mais le code le change. Le résumé d’une modification, fourni par un assistant ou une personne, est une affirmation. Les différences montrent la modification.
L’idée : réviser le code, une ligne à la fois
Section intitulée « L’idée : réviser le code, une ligne à la fois »Une révision de code est une lecture attentive d’une modification par quelqu’un qui ne l’a pas écrite, avant son acceptation. Vous l’avez rencontrée dans le cours sur Git, pour la demande de tirage (pull request) d’un collègue. Avec un assistant, cette personne, c’est toujours vous, car personne d’autre n’a lu le code avant vous.
Lisez chaque ligne ajoutée et posez quatre questions :
- Est-ce une modification sans rapport? La tâche ne la demandait pas : variable renommée, commentaire réécrit, test reformaté.
- Est-ce qu’elle change un contrat? Un contrat définit ce sur quoi d’autres codes ou personnes comptent : clés du rapport, lignes affichées, codes de sortie.
- Est-ce qu’elle cache une hypothèse? Le code suppose quelque chose sur l’entrée : orthographe, valeur unique plutôt que plusieurs, terminal d’une certaine largeur.
- Est-ce un problème de maintenabilité? La prochaine personne aura du mal à lire ou modifier le code : lignes longues, logique dupliquée, nom trompeur.
Attribuez ensuite une marque à chaque ligne : nécessaire (la tâche en a besoin, et elle est correcte), sans rapport (question 1) ou risquée (questions 2 à 4). Une ligne risquée n’est pas toujours incorrecte. C’est une ligne que vous devez vérifier avant de l’accepter.
Un petit exemple : quatre lignes ajoutées
Section intitulée « Un petit exemple : quatre lignes ajoutées »Voici la première partie du candidat A, dans ticket_cleaner/cli.py. Les quatre lignes ajoutées sont les lignes 31 à 34 du nouveau fichier :
help="which tickets to count (default: open)",)parser.add_argument( "--category", help="only count tickets in this category (exact match; default: all categories)",)- Les lignes 31, 32 et 34 sont nécessaires. La tâche exige une option, et
--categoryest le nom donné dans l’énoncé. - La ligne 33 est risquée. Le texte d’aide le dit clairement : « correspondance exacte ». Donc,
--category Billingne trouve rien. Il dit aussi « cette catégorie » : une seule. L’option n’a pas deaction="append", donc un deuxième--categoryremplace le premier, sans erreur.
Quatre lignes cachent deux hypothèses, et vous pouvez voir les deux en lisant les mots. Vous n’aviez rien à exécuter. Il vous fallait l’énoncé à côté des différences.
Révisez vous-même le candidat A
Section intitulée « Révisez vous-même le candidat A »L’explorateur montre la partie code du candidat A : 43 lignes ajoutées dans cli.py, report.py et tests/test_report.py. Marquez d’abord les lignes. Affichez ensuite la révision de l’équipe du cours et comparez.
Explorer
Marquez chaque ligne ajoutée du candidat A
Prédisez d’abord : Combien des 43 lignes ajoutées remettriez-vous en question? Quel fichier en contient le plus?
- Vos marques
- -
- La revue
- 5 risquées, 1 sans rapport, 37 utiles
- Trouvées
- -
La revue de chaque ligne ajoutée. Avec JavaScript, vous marquez d’abord les lignes vous-même.
| Revue | Ligne | Code |
|---|---|---|
@@ -28,6 +28,10 @@ def make_parser() -> argparse.ArgumentParser: | ||
| 28 | choices=sorted(STATUSES), | |
| 29 | help="which tickets to count (default: open)", | |
| 30 | ) | |
| utile | 31 | + parser.add_argument( |
| utile | 32 | + "--category", |
| risquée | 33 | + help="only count tickets in this category (exact match; default: all categories)", |
Says 'exact match' out loud: one category only, and the spelling must be exact. | ||
| utile | 34 | + ) |
| 35 | parser.add_argument( | |
| 36 | "--output", | |
| 37 | type=Path, | |
@@ -62,7 +66,7 @@ def main(argv: list[str] | None = None) -> int: | ||
| 66 | for record in rejected: | |
| 67 | logger.warning("row %d rejected: %s", record.row, "; ".join(record.problems)) | |
| 68 | | |
- summary = build_summary(tickets, rejected, args.status) | ||
| utile | 69 | + summary = build_summary(tickets, rejected, args.status, category=args.category) |
| 70 | write_json(summary, args.output) | |
| 71 | logger.info("wrote %s", args.output) | |
| 72 | print(f"{len(rows)} rows: {len(tickets)} valid, {len(rejected)} rejected.") | |
| Revue | Ligne | Code |
|---|---|---|
@@ -6,6 +6,11 @@ def filter_by_status(tickets: list[Ticket], status: str = "open") -> list[Ticket | ||
| 6 | return [ticket for ticket in tickets if ticket.status == status] | |
| 7 | | |
| 8 | | |
| utile | 9 | +def filter_by_category(tickets: list[Ticket], category: str) -> list[Ticket]: |
| utile | 10 | + """Return the tickets that have the given category.""" |
| risquée | 11 | + return [ticket for ticket in tickets if ticket.category == category] |
Exact match: --category Billing or ' billing' finds nothing. The tickets' categories are in small letters. | ||
| utile | 12 | + |
| utile | 13 | + |
| 14 | def count_by_category(tickets: list[Ticket]) -> dict[str, int]: | |
| 15 | """Return the number of tickets in each category, sorted by category.""" | |
| 16 | counts = {} | |
@@ -21,11 +26,19 @@ def average_priority(tickets: list[Ticket]) -> float | None: | ||
| 26 | return round(sum(ticket.priority for ticket in tickets) / len(tickets), 1) | |
| 27 | | |
| 28 | | |
-def build_summary(tickets: list[Ticket], rejected: list[Rejected], status: str) -> dict: | ||
- """Return the report as a dictionary that can be saved as JSON.""" | ||
| utile | 29 | +def build_summary( |
| utile | 30 | + tickets: list[Ticket], |
| utile | 31 | + rejected: list[Rejected], |
| utile | 32 | + status: str, |
| utile | 33 | + category: str | None = None, |
| utile | 34 | +) -> dict: |
| 35 | + """Return a report filtered by status and, optionally, category.""" | |
Rewrites the docstring of build_summary; the old one was still true. | ||
| 36 | selected = filter_by_status(tickets, status) | |
| utile | 37 | + if category is not None: |
| utile | 38 | + selected = filter_by_category(selected, category) |
| 39 | return { | |
| 40 | "status": status, | |
| risquée | 41 | + "category": category, |
Changes the contract: every report gets a new key, also without --category. Grace's spreadsheet reads the report. | ||
| 42 | "valid_records": len(tickets), | |
| 43 | "selected": len(selected), | |
| 44 | "by_category": count_by_category(selected), | |
| Revue | Ligne | Code |
|---|---|---|
@@ -25,6 +25,29 @@ def test_categories_are_in_alphabetical_order(tickets): | ||
| 25 | assert list(count_by_category(tickets)) == ["billing", "login"] | |
| 26 | | |
| 27 | | |
| utile | 28 | +def test_summary_without_category_includes_all_categories(tickets): |
| utile | 29 | + summary = build_summary(tickets, [], status="open") |
| risquée | 30 | + assert summary["category"] is None |
The test checks the new key, so the test repeats the contract change instead of catching it. | ||
| utile | 31 | + assert summary["selected"] == 2 |
| utile | 32 | + assert summary["by_category"] == {"billing": 1, "login": 1} |
| utile | 33 | + |
| utile | 34 | + |
| utile | 35 | +def test_summary_filters_by_both_status_and_category(tickets): |
| utile | 36 | + summary = build_summary(tickets, [], status="closed", category="billing") |
| risquée | 37 | + assert summary["category"] == "billing" |
The test checks the new key, so the test repeats the contract change instead of catching it. | ||
| utile | 38 | + assert summary["valid_records"] == 3 |
| utile | 39 | + assert summary["selected"] == 1 |
| utile | 40 | + assert summary["by_category"] == {"billing": 1} |
| utile | 41 | + assert summary["average_priority"] == 2.0 |
| utile | 42 | + |
| utile | 43 | + |
| utile | 44 | +def test_summary_for_a_category_with_no_tickets(tickets): |
| utile | 45 | + summary = build_summary(tickets, [], status="open", category="unknown") |
| utile | 46 | + assert summary["selected"] == 0 |
| utile | 47 | + assert summary["by_category"] == {} |
| utile | 48 | + assert summary["average_priority"] is None |
| utile | 49 | + |
| utile | 50 | + |
| 51 | def test_summary_for_a_status_with_no_tickets(tickets): | |
| 52 | summary = build_summary(tickets, [], status="pending") | |
| 53 | assert summary["selected"] == 0 | |
Description textuelle de l’explorateur
L’explorateur montre les vraies différences du candidat A, avec un tableau par fichier. Les fichiers sont ticket_cleaner/cli.py (5 lignes ajoutées), ticket_cleaner/report.py (15) et tests/test_report.py (23). Chaque ligne ajoutée porte une marque : nécessaire, sans rapport ou risquée. Toutes les lignes sont marquées nécessaires au départ. La révision montre l’étiquette de l’équipe du cours, votre marque et une raison pour chaque ligne non nécessaire :
- cli.py, ligne 33, risquée : le texte d’aide dit « correspondance exacte » : une catégorie, orthographe exacte.
- report.py, ligne 11, risquée :
ticket.category == categoryexige une correspondance exacte, donc--category Billingne trouve rien. - report.py, ligne 35, sans rapport : la chaîne de documentation de
build_summaryest réécrite, mais l’ancienne était encore correcte. - report.py, ligne 41, risquée :
"category": category,ajoute une clé à chaque rapport, même sans l’option. - tests/test_report.py, lignes 30 et 37, risquées : les tests vérifient la nouvelle clé, donc ils reproduisent le changement de contrat.
Les 37 autres lignes ajoutées sont nécessaires.
Avez-vous marqué les deux lignes de test? Elles passent facilement inaperçues, car un test ressemble à une preuve. Mais un test qui vérifie la nouvelle clé transforme la modification en promesse. Si la clé est une erreur, le test protège maintenant cette erreur.
Larkfield : une liste de vérification pour chaque modification
Section intitulée « Larkfield : une liste de vérification pour chaque modification »Amira ne se fie pas à sa mémoire pour cela. Elle écrit une courte liste de vérification et la conserve dans le projet, dans docs/review-checklist.md. Elle comporte cinq parties :
- Périmètre : seulement les fichiers de la tâche, aucune modification sans rapport, aucun fichier de données supprimé ou modifié.
- Comportement et contrats : chaque critère a du code et un test. Le rapport et les codes de sortie changent seulement si la tâche le demande. Les cas limites fonctionnent, et les tests échoueraient sans la modification.
- Dépendances : aucun nouveau paquet, ou un paquet qui a réussi les vérifications de la prochaine leçon.
- Sécurité et données : entrée vérifiée avant de servir de chemin ou de commande; aucun secret affiché ou consigné; rien supprimé sans demander. La leçon suivante après la prochaine porte sur cette partie.
- Vérifications que j’ai exécutées moi-même : les tests, ruff et les commandes de la tâche.
La dernière partie compte surtout avec un assistant. Un outil peut afficher « tous les tests passent » dans sa conversation. Seule votre propre exécution, dans votre propre terminal, constitue une preuve.
Voici la liste de vérification appliquée au candidat A. Chaque constat contient une preuve qu’un collègue pourrait vérifier :
Description textuelle du diagramme
Une ligne par section de la liste de vérification, avec le constat et sa preuve. Les lignes rouges échouent, les vertes réussissent, et l’orange indique un avertissement.
- Périmètre (avertissement) : les 4 fichiers sont autorisés. Mais la chaîne de documentation de
build_summary()est réécrite, etREADME.mdn’a aucune ligne pour l’option (critère 7). - Comportement et contrats (échec) : chaque rapport reçoit une nouvelle clé,
"category": null, même sans l’option. Preuve :tests/test_baseline.pyéchoue avecLeft contains 1 more item: {'category': None}(la partie gauche contient un élément supplémentaire). - Cas limites (échec) : correspondance exacte, une seule catégorie.
--category " Billing "donneselected(sélectionnés) 0;--category billing --category shippingdonne{"shipping": 1}. - Tests (échec) :
assert summary["category"] is None: les nouveaux tests reproduisent la modification. - Dépendances (réussite) : aucun nouveau paquet; les fichiers de dépendances ne changent pas.
- Sécurité et données (réussite) :
--categoryest seulement comparé aux noms : aucun chemin, aucune commande, aucun secret. - Vérifications que j’ai exécutées moi-même (échec) :
1 failed, 30 passed(1 échec, 30 réussites);ruff format --check .indique1 file would be reformatted(1 fichier serait reformaté).
Décision : rejeter le candidat A et renvoyer les constats avec l’énoncé de tâche.
Remarquez le test de référence de base. Dans la session enregistrée, le projet n’avait pas de tests/test_baseline.py, donc les 29 tests réussissaient. Votre projet l’a, depuis Préparer le dépôt. Dans votre projet, les mêmes différences font donc échouer un test. Ce test existe précisément pour ce moment.
Révisez le candidat A dans votre projet
Section intitulée « Révisez le candidat A dans votre projet »-
Vérifiez l’état de départ.
git statusindiqueworking tree clean, etpython -m pytestaffiche26 passed. Un départ propre signifie quegit diffmontre seulement le candidat. -
Appliquez le candidat A.
git applymodifie les fichiers selon le correctif, sans créer de commit (enregistrement des modifications) :Fenêtre de terminal git apply ../nextia-learning-labs/C15/candidates/A-vague-request.patchAucune sortie signifie que le correctif a été appliqué.
-
Regardez d’abord le périmètre :
Fenêtre de terminal git diff --statSortie tests/test_cli.py | 34 ++++++++++++++++++++++++++++++++++tests/test_report.py | 23 +++++++++++++++++++++++ticket_cleaner/cli.py | 6 +++++-ticket_cleaner/report.py | 17 +++++++++++++++--4 files changed, 77 insertions(+), 3 deletions(-)Comparez-le aux contraintes de l’énoncé :
cli.py,report.py,README.mdet les tests. Tous les fichiers sont autorisés. Un fichier autorisé manque :README.md. -
Lisez la partie code des différences, avec l’énoncé ouvert à côté :
Fenêtre de terminal git diff ticket_cleaner/Retrouvez les lignes de l’explorateur : texte d’aide,
==dansfilter_by_category(), nouvelle chaîne de documentation et clé"category": category,. -
Exécutez vous-même les tests :
Fenêtre de terminal python -m pytestOutput (the end) FAILED tests/test_baseline.py::test_report_of_the_sample_file_is_unchanged - ...========================= 1 failed, 30 passed in 0.05s =========================Plus haut, la sortie montre pourquoi :
Sortie (extrait) E Left contains 1 more item:E {'category': None} -
Exécutez deux commandes de l’énoncé. Chacune affiche
15 rows: 9 valid, 6 rejected.(15 lignes : 9 valides, 6 rejetées) et écritreports/summary.json. Ouvrez le rapport après chaque commande et comparez-le à l’énoncé :Fenêtre de terminal python -m ticket_cleaner data/tickets.csv --category " Billing "python -m ticket_cleaner data/tickets.csv --category billing --category shippingLe premier rapport contient
"selected": 0et"by_category": {}, mais l’énoncé attend 2 billets de soutien de facturation. Le deuxième rapport contient"category": "shipping"et"by_category": {"shipping": 1}. Les billets de facturation ont disparu, sans aucune indication. -
Exécutez la vérification du format :
Fenêtre de terminal ruff format --check .Output (the end) 1 file would be reformatted, 19 files already formatted -
Rejetez le candidat.
git restore .rétablit chaque fichier modifié à partir du dernier commit :Fenêtre de terminal git restore .git status --shortpython -m pytestgit status --shortn’affiche rien, et les tests affichent26 passed.
Notez vos constats, comme dans le diagramme, avant de restaurer les fichiers. Ils accompagnent l’énoncé envoyé à la personne qui demandera le prochain essai.
La modification acceptée, après révision
Section intitulée « La modification acceptée, après révision »Amira n’a pas refait la demande en une phrase. Au module 2, l’équipe du cours a donné l’énoncé de tâche à l’assistant (session feature-bounded, réelle). Cette modification a réussi les 8 vérifications d’acceptation. Sa révision a quand même relevé trois points :
ruff format --check .échouait, car deux lignes étaient trop longues.- La chaîne de documentation de
build_summary()n’énonçait pas la règle importante : la clécategoriesapparaît seulement avec l’option. - Ses tests comparaient tout le rapport dans un grand test paramétré. Ils étaient corrects, mais difficiles à lire à côté des autres tests du projet.
Amira a conservé la conception : le filtre après celui du statut, et la clé categories seulement avec l’option. Elle a corrigé elle-même les trois points. Le résultat se trouve dans l’instantané end-of-m03. Vous le copiez, puis vous le révisez comme s’il était nouveau, car il est nouveau pour vous.
-
Ajoutez la liste de vérification au projet et créez un commit distinct pour elle :
Fenêtre de terminal mkdir -p docscp ../nextia-learning-labs/C15/snapshots/end-of-m03/docs/review-checklist.md docs/git add docs/review-checklist.mdgit commit -m "Add a checklist for reviewing a generated change"Fenêtre de terminal New-Item -ItemType Directory -Force docsCopy-Item ..\nextia-learning-labs\C15\snapshots\end-of-m03\docs\review-checklist.md docs\git add docs/review-checklist.mdgit commit -m "Add a checklist for reviewing a generated change"Output (the commit) [feature/category-option 8281ea5] Add a checklist for reviewing a generated change1 file changed, 41 insertions(+)create mode 100644 docs/review-checklist.mdL’empreinte de votre commit est différente.
-
Copiez la modification acceptée : deux fichiers de code, deux fichiers de tests et le README.
Fenêtre de terminal S=../nextia-learning-labs/C15/snapshots/end-of-m03cp $S/ticket_cleaner/cli.py $S/ticket_cleaner/report.py ticket_cleaner/cp $S/tests/test_cli.py $S/tests/test_report.py tests/cp $S/README.md .Fenêtre de terminal $S = "..\nextia-learning-labs\C15\snapshots\end-of-m03"Copy-Item "$S\ticket_cleaner\cli.py", "$S\ticket_cleaner\report.py" ticket_cleaner\Copy-Item "$S\tests\test_cli.py", "$S\tests\test_report.py" tests\Copy-Item "$S\README.md" . -
Révisez le périmètre :
Fenêtre de terminal git diff --statSortie README.md | 9 +++++++++tests/test_cli.py | 19 +++++++++++++++++++tests/test_report.py | 39 +++++++++++++++++++++++++++++++++++++++ticket_cleaner/cli.py | 8 +++++++-ticket_cleaner/report.py | 22 +++++++++++++++++++---5 files changed, 93 insertions(+), 4 deletions(-) -
Lisez
git diff ticket_cleaner/avec la liste de vérification. L’option contientaction="append"etmetavar="NAME", donc elle peut se répéter.build_summary()nettoie chaque nom avecname.strip().lower(), filtre après le filtre de statut et ajoute"categories"seulement sicategories is not None.valid_recordscompte toujours tous les billets. Le filtre compare les noms àticket.categorytel qu’il est stocké, donc il ne contourne pas le bogue de Grace. Sur son exportation,--category loginsélectionne 2 billets de connexion, pas 4. La correction arrive dans Déboguer et tester avec l’assistant. -
Exécutez vous-même les vérifications :
Fenêtre de terminal python -m pytestruff check .ruff format --check .Output (the end of each command) ============================== 34 passed in 0.04s ==============================All checks passed!21 files already formattedLe test de référence de base réussit : sans
--category, le rapport n’a pas changé. -
Exécutez une commande de l’énoncé et comparez le rapport à vos valeurs du module 2 :
Fenêtre de terminal python -m ticket_cleaner data/tickets.csv --category billing --category shippingLe rapport contient
"selected": 3,"by_category": {"billing": 2, "shipping": 1},"valid_records": 9et"categories": ["billing", "shipping"]. De même,--category " Billing "donne"selected": 2, et--category gardendonne"selected": 0avec le code de sortie 0. -
Créez un commit pour la modification :
Fenêtre de terminal git add -Agit commit -m "Add the --category option, after review"Sortie (extrait) 5 files changed, 93 insertions(+), 4 deletions(-)
Regardez la taille. La modification acceptée compte +93 −4 dans cinq fichiers, et le candidat A comptait +77 −3 dans quatre. La meilleure modification est la plus grande. La taille ne décide jamais d’une révision : les critères et la lecture ligne par ligne le font.
Quand réviser, et combien cela coûte
Section intitulée « Quand réviser, et combien cela coûte »Révisez chaque modification avant de l’accepter : celle d’un assistant, d’un collègue ou de vous-même la semaine dernière. La révision est le moment où vous prenez la responsabilité du code. Après, « l’assistant l’a écrit » ne répond plus à aucune question.
Une révision attentive prend du temps, et ce temps augmente avec la taille des différences. C’est la meilleure raison de choisir de petites tâches et étapes, comme dans Découper le travail en étapes. Si les différences sont trop volumineuses pour une seule séance de lecture, ne les survolez pas. Demandez une modification plus petite.
Une révision a des limites. Elle trouve ce qu’une personne attentive peut voir et manque ce que personne n’a pensé à vérifier. Elle complète donc les tests et les commandes de l’énoncé, sans les remplacer. Ajoutez une ligne à la liste de vérification chaque fois qu’une révision manque quelque chose.
Erreur courante
git diff ne montre rien, mais les fichiers ont changé
Symptôme : un agent dit avoir modifié trois fichiers. Vous exécutez git diff --stat, qui n’affiche rien. Vous concluez qu’il n’y a rien à réviser.
Cause : certains assistants créent des commits pour leurs propres modifications. La modification est alors dans un commit, et git diff compare vos fichiers à ce commit : aucune différence. Le cours a enregistré ses sessions avec les commits désactivés, mais les paramètres par défaut d’un outil peuvent différer.
Diagnostic : regardez l’historique :
git log --oneline -3git show --stat HEADac7ea70 Add a way to filter the report by category951e017 Start
ac7ea70 Add a way to filter the report by category tests/test_cli.py | 34 ++++++++++++++++++++++++++++++++++ tests/test_report.py | 23 +++++++++++++++++++++++ ticket_cleaner/cli.py | 6 +++++- ticket_cleaner/report.py | 17 +++++++++++++++-- 4 files changed, 77 insertions(+), 3 deletions(-)Solution : révisez le commit avec git show HEAD, ou toute la branche avec git diff main...feature/category-option, les trois points du cours sur Git. Pour rejeter le commit, Amira exécute elle-même git reset --hard HEAD~1, après avoir vérifié qu’il ne contient rien d’autre. Elle désactive ensuite les commits automatiques dans les paramètres de l’outil, comme l’indique son fichier de périmètre : elle exécute elle-même git commit.
À vous de jouer : révisez la proposition B
Section intitulée « À vous de jouer : révisez la proposition B »La proposition B est réelle. L’équipe du cours a donné à l’assistant le même énoncé de tâche et ajouté une phrase : « Pendant que vous travaillez dans ces fichiers, améliorez le code partout où vous le pouvez. » Elle a réussi les 8 vérifications d’acceptation, avec +171 −10 dans cinq fichiers.
Ouvrez nextia-learning-labs/C15/candidates/B-improve-while-there.patch dans votre éditeur. C’est un fichier texte, alors vous n’avez pas besoin de l’appliquer. Utilisez la liste de vérification et trouvez :
- Deux modifications que la tâche ne demandait pas.
- Un test qui dépend de quelque chose d’extérieur au code.
- Une décision concernant le bogue de Grace que l’énoncé ne précisait pas.
Afficher la réponse
- Modifications sans rapport avec la tâche. Dans
report.py,counts = {}devientcounts: dict[str, int] = {}danscount_by_category(), une fonction que la tâche ne touche pas. Danstests/test_cli.py, le test existanttest_report_for_pending_ticketsest regroupé sur une seule longue ligne. Aucune de ces modifications ne change le comportement, mais les deux augmentent les différences et ralentissent la révision. La longue ligne échoue aussi à la vérification du format :ruff format --check .indiquetests/test_cli.py:10. - Un test qui dépend du terminal.
test_help_describes_category_optionvérifie que le texte d’aide contient"repeat for multiple categories"(répéter pour plusieurs catégories).argparserépartit le texte d’aide sur plusieurs lignes selon la largeur du terminal. L’équipe du cours l’a mesuré :1 failed, 35 passed(1 échec, 35 réussites) dans un terminal de 80 colonnes, et36 passed(36 réussites) dans un terminal de 160 colonnes. Le test réussit sur un écran large et échoue sur celui, plus étroit, d’un collègue. C’est une hypothèse cachée. - Une décision concernant le bogue de Grace. B compare
ticket.category.strip().lower(), donc--category logincompte aussi les billets stockés sousLOGIN. Cela contourne discrètement le bogue de Grace pour cette option seulement, tandis queby_categoryprésente encoreLOGINetloginséparément. Le plan du module 2 prévoyait le contraire : le bogue constitue une tâche distincte, avec sa propre correction et son propre test.
« Améliorez partout où vous le pouvez » demandait des décisions que personne n’avait révisées. Une révision les repère, et chacune retourne au responsable de la tâche.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
Nommez les quatre questions à poser pour chaque ligne ajoutée, avec une ligne de la proposition A pour chaque question.
Afficher la réponse
- Modification sans rapport avec la tâche?
"""Return a report filtered by status and, optionally, category.""": l’ancienne chaîne de documentation debuild_summary()était encore exacte. - Contrat modifié?
"category": category,: chaque rapport reçoit une nouvelle clé, même sans l’option. - Hypothèse cachée?
return [ticket for ticket in tickets if ticket.category == category]: la correspondance est exacte, doncBillingne trouve rien. Le texte d’aide « this category » (cette catégorie) signifie aussi une seule catégorie. - Problème de maintenabilité? Le nouveau test
test_report_for_a_category_with_no_ticketsdanstests/test_cli.pyéchoue àruff format --check. Le format du projet n’est donc pas respecté.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Dans l'enregistrement, la proposition A donnait 29 réussites. Dans votre projet, la même modification donnait 1 échec et 30 réussites. Expliquez la différence et ce qu'elle révèle sur les tests de référence de base.
Afficher la réponse
L’enregistrement utilisait l’instantané start, qui ne contient pas tests/test_baseline.py. Votre projet contient ce test depuis le module 1. Il fixe comme référence le rapport de data/tickets.csv tel qu’il était avant toute modification. La proposition A ajoute "category": null à chaque rapport, donc le rapport de référence ne correspond plus : Left contains 1 more item: {'category': None} (la partie gauche contient un élément de plus). Les propres tests de l’assistant ne pouvaient pas détecter cela, car l’assistant les avait écrits pour sa propre décision. Un test écrit avant la modification, pour le comportement qui doit rester inchangé, peut le détecter.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Tomás dit : « La modification acceptée est plus grosse que la proposition A : +93 contre +77. Nous avions demandé quelque chose de simple, donc A était le meilleur résultat. » Répondez-lui.
Afficher la réponse
La taille ne détermine pas le résultat d’une révision. La proposition A est plus petite parce qu’elle en fait moins : une catégorie, une correspondance exacte et aucune ligne dans le README. Elle change aussi le rapport pour tout le monde. La modification acceptée répond à l’énoncé, et chaque critère a un test. Ses lignes supplémentaires concernent l’option répétable, le nettoyage des noms, la clé categories seulement avec l’option, le README et les tests. Chacune correspond à un critère. Pour chaque ligne, demandez : « La tâche en a-t-elle besoin, et est-elle correcte? », plutôt que « Combien de lignes y a-t-il? ».
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Récapitulatif
- Une exécution réussie des tests constitue une preuve parmi d’autres. Une révision du code examine chaque ligne ajoutée avant que vous acceptiez la modification.
- Posez quatre questions pour chaque ligne : modification sans rapport avec la tâche, contrat modifié, hypothèse cachée, problème de maintenabilité. Marquez-la comme nécessaire, sans rapport ou risquée.
- La proposition A a réussi ses propres tests et échoué à la révision. Elle ajoutait une clé à chaque rapport, exigeait une correspondance exacte et acceptait une seule catégorie. Ses tests reproduisent la modification. Dans votre projet, le test de référence de base a détecté la nouvelle clé.
docs/review-checklist.mdrend la révision uniforme. Sa dernière partie, « checks that I ran myself » (vérifications que j’ai exécutées moi-même), est celle qu’un assistant ne peut pas faire pour vous.- Votre projet contient la modification acceptée :
34 passed(34 réussites), et deux nouveaux commits (enregistrements des modifications) surfeature/category-option.
Ensuite, une modification arrive qui ajoute un paquet au projet. Avant toute installation, vous vérifiez le paquet.
Leçon suivante : Vérifier les dépendances