Réusiner de façon sélective
- Leçon 13
- 40 min
- Module 5 : Livrer un travail facile à maintenir
Où nous en sommes
Dans le module 4, nous avons débogué à partir de preuves et gardé seulement les tests utiles. Maintenant, nous préparons le projet pour le transmettre. Un assistant à qui l'on demande de « rendre le code plus propre » change beaucoup de choses qu'aucune tâche ne demandait, et chacune coûte du temps de révision. Dans cette leçon, nous changeons la structure seulement là où la modification demandée l'exige, et nous notons chaque autre amélioration comme une tâche distincte, comme un menuisier qui pose une tablette, pas une nouvelle cuisine.
Leçon 13 sur 15 · Développement logiciel assisté par l'IARéusiner de façon sélective
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
Changez la structure du code seulement là où le changement demandé l’exige. Gardez toute autre amélioration pour une tâche distincte. Un changement ciblé est plus facile à réviser, à tester et à annuler.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
- Ce qu’est un réusinage : un changement de structure du code qui ne change pas son fonctionnement. Vous en avez fait un dans Le contrat d’une fonction, dans Python pour l’ingénierie de l’IA en pratique.
- Comment un test qui échoue d’abord prouve une correction, selon Choisir des vérifications utiles.
- Comment lire les différences et utiliser la liste de vérification, selon Examiner les différences.
Ce qu’il vous faut sur votre ordinateur
- Le projet
~/projects/ticket-cleaner-assistà la fin du module 4, sur la branchefeature/category-option, avec son environnement actif.python -m pytestaffiche39 passed(39 tests réussis), etgit status --shortn’affiche rien. - Le dossier d’exercices
~/projects/nextia-learning-labs, avecC15/transcripts/. - Si le projet manque ou ne fonctionne plus, suivez les étapes de réinitialisation de Contexte et limites. Utilisez l’instantané
end-of-m04au lieu deend-of-m01. Elles créent le projet de fin du module 4, avecmainau début du cours. - Aucun compte, aucune clé et aucun paiement. Les changements de l’assistant dans cette leçon viennent de séances enregistrées.
Une tablette, pas une nouvelle cuisine
Section intitulée « Une tablette, pas une nouvelle cuisine »Vous demandez à un menuisier d’installer une tablette dans votre cuisine. Derrière l’emplacement de la tablette, une cheville murale tient mal. Le menuisier fixe d’abord la cheville, parce qu’elle soutient la tablette. Cela fait partie du travail.
Imaginez maintenant que le menuisier peint aussi les armoires et déplace la cuisinière, « parce que c’était plus beau ». La cuisine est peut-être plus jolie. Mais vous avez demandé une tablette. Vous devez maintenant vérifier aussi les armoires et la cuisinière. Avant cela, vous ne pouvez pas savoir si la tablette est sûre.
La cheville mal fixée était nécessaire au travail. La peinture ne l’était pas. Cette leçon traite de cette différence, dans le code.
Le problème : « rendre le code plus propre »
Section intitulée « Le problème : « rendre le code plus propre » »Dans Contexte et limites, vous avez découvert la séance enregistrée refactor-open. L’équipe du cours a donné à un assistant les fichiers de ticket_cleaner/ et une phrase :
Refactor the code in ticket_cleaner/ to make it cleaner and easier to maintain.Avant ses modifications, l’assistant a annoncé ce qu’il ferait :
I’ll simplify record validation, use `Counter` for category totals, and make JSON writes safer with unique temporary files and cleanup. Public function namesand the report format will stay unchanged.Le changement comptait 3 files, +40 −21 (3 fichiers, 40 lignes ajoutées et 21 supprimées). Les 24 tests réussissaient avant et après. Examinez maintenant chaque modification et demandez-vous quelle tâche l’exige.
Description textuelle du diagramme
Une ligne par modification, avec ce qu’elle change et la tâche qui l’exige :
files.py,write_json(): réécrit avecNamedTemporaryFileettry/finally. Tous les rapports passent par cette fonction. Aucune tâche ne l’exige. L’assistant a dit que c’était « plus sûr », mais aucun test ne le montre.parsing.py,split_records(): la boucle est réécrite aveccontinue. Aucune tâche ne l’exige. Elle se trouve dans le même fichier que le bogue de Grace.parsing.py,find_problems(): une annotation de type,raw: dict→raw: object. Aucune tâche.report.py,count_by_category(): une boucle →collections.Counter. Aucune tâche.files.py,read_rows():open(path)→path.open(), deux fois. Seulement du style.- Absent des différences :
clean_category(). La ligne contenant le bogue de Grace n’a pas changé. Son exportation affiche donc encoreBilling,LOGINetLoginà côté debillingetlogin.
Chaque modification peut être une petite amélioration. Ce n’est pas le problème. Le problème, c’est que vous n’avez aucun critère pour les réviser. « Plus propre » n’a aucun critère d’acceptation. Aucun test n’échoue avant pour réussir après. Vous ne pouvez donc pas dire quand le travail est terminé, ni s’il est correct. Vous pouvez seulement dire que rien de ce que vous testez n’a cessé de fonctionner.
Deux modifications présentent un vrai risque. write_json() enregistre tous les rapports que Grace lit. Cette fonction fonctionne maintenant autrement, sans test pour le vérifier. Et la boucle dans split_records() décide quels enregistrements sont rejetés. Ses tests réussissent aujourd’hui, mais un réviseur doit maintenant lire 28 lignes modifiées de parsing.py pour s’en assurer. Pendant ce temps, le code dont Grace se plaignait n’a pas changé.
Dans Examiner les différences, vous avez vu le même phénomène sous un autre angle. La fiche de tâche avec « améliorez le code partout où vous le pouvez » (candidat B) a réussi les 8 vérifications d’acceptation. Elle a aussi ajouté des modifications sans rapport et un test qui échoue dans un terminal de 80 colonnes.
Tomás aime encore l’idée :
« Puisqu’on est déjà dans
report.py, laissons l’assistant nettoyer tout le paquet. Ça coûte peu, et les tests passent. »
Les tests réussissent parce qu’aucun test ne vérifie ce qui a changé. Et le coût n’est pas faible. Vous payez en temps de révision, en risques et en conflits, comme le montre le cas d’échec ci-dessous.
L’idée : réusiner seulement ce que le changement exige
Section intitulée « L’idée : réusiner seulement ce que le changement exige »Un réusinage change la structure du code sans changer son comportement. Vous en avez fait un dans le cours de Python : la sortie était identique avant et après. Un réusinage peut clarifier un nom, diviser une longue fonction ou éliminer la duplication : la même règle écrite à deux endroits.
Réusiner de façon sélective, c’est réusiner seulement là où cela aide à réaliser le changement demandé. Posez une question pour chaque amélioration que vous voulez faire :
Le changement demandé en a-t-il besoin pour être correct, plus simple ou sûr à ajouter?
- Oui : faites-la dans cette tâche. Si elle change le fonctionnement du programme, écrivez un test qui échoue d’abord. Donnez-lui son propre commit (enregistrement des changements).
- Non : notez-la comme tâche distincte. Ne la faites pas maintenant, même si elle est petite, et même si un assistant la propose.
Description textuelle du diagramme
- Le changement demandé en a-t-il besoin pour être correct, plus simple ou sûr à ajouter? Sinon, notez-la comme tâche distincte. Les modifications de
refactor-openentrent dans cette catégorie. - Si oui : cela change-t-il le fonctionnement du programme? Sinon, c’est un réusinage pur, et les tests existants doivent réussir sans modification. Si oui, écrivez un test qui échoue d’abord, puis faites le changement et consignez la décision.
Dans les deux cas, donnez-lui son propre commit et relancez les tests et ruff.
Pourquoi cette discipline en vaut-elle la peine? Un réviseur peut vérifier un changement ciblé par rapport à sa tâche. Un commit ciblé peut être annulé seul. Et un petit ensemble de différences laisse le reste du code tel que vos collègues le connaissent.
Un petit exemple : deux règles pour une idée
Section intitulée « Un petit exemple : deux règles pour une idée »La duplication est la raison la plus courante de faire un réusinage nécessaire au changement. En voici un exemple dans ticket-cleaner, à la fin du module 4. Deux endroits nettoient un nom de catégorie, avec deux règles différentes :
clean_category()dansparsing.pynettoie la catégorie de chaque billet de soutien. Elle supprime les espaces aux extrémités, utilise des minuscules et remplace les noms du formulaire Web par les nôtres :Sign-in(connexion) devientlogin.build_summary()dansreport.pynettoie les noms que vous donnez à--category. Elle utilise seulementname.strip().lower().
L’auteur a exécuté les deux règles sur quatre noms :
'Sign-in' report.py: 'sign-in' clean_category: 'login'' LOGIN ' report.py: 'login' clean_category: 'login''Invoice' report.py: 'invoice' clean_category: 'billing''biling' report.py: 'biling' clean_category: 'biling'Pour " LOGIN " et biling, les deux règles donnent le même résultat. Pour les noms du formulaire Web, ce n’est pas le cas. Les billets indiquent login, mais l’option cherche sign-in, et aucun billet n’a cette catégorie.
Description textuelle du diagramme
Ce que --category NAME sélectionne dans l’exportation de Grace, avec chaque règle :
--category |
Règle du module 4 (report.py) |
clean_category() |
|---|---|---|
Sign-in |
'sign-in' → 0 billet sélectionné |
'login' → 4 billets sélectionnés |
Invoice |
'invoice' → 0 billet sélectionné |
'billing' → 3 billets sélectionnés |
" LOGIN " |
'login' → 4 billets sélectionnés |
'login' → 4 billets sélectionnés |
biling |
'biling' → 0 billet sélectionné |
'biling' → 0 billet sélectionné |
Le réusinage sélectif : report.py appelle clean_category(). Une seule règle, à un seul endroit.
Larkfield : Grace tape le nom du formulaire
Section intitulée « Larkfield : Grace tape le nom du formulaire »Grace essaie la nouvelle option sur son exportation. Elle pense aux noms du formulaire Web, parce que son équipe les voit chaque jour. Elle tape donc Sign-in :
-
Exécutez la commande de Grace dans votre projet :
Fenêtre de terminal python -m ticket_cleaner data/web-form-export.csv --category Sign-inSortie 12 rows: 12 valid, 0 rejected.Report: reports/summary.jsonLe code de sortie est 0, donc rien ne semble incorrect. Ouvrez
reports/summary.json:reports/summary.json (part) "selected": 0,"by_category": {},"average_priority": null,"rejected": [],"categories": ["sign-in"]La même commande avec
--category loginsélectionne 4 billets. Trois venaient du formulaire sous les nomsSign-in,LoginetLOGIN. -
Trouvez chaque endroit qui nettoie un nom.
grepcherche du texte dans les fichiers. Sous Windows, utilisezSelect-String(non testé) :Fenêtre de terminal grep -n "strip().lower()" ticket_cleaner/*.pyFenêtre de terminal Select-String -Pattern "strip().lower()" -SimpleMatch ticket_cleaner\*.pySortie ticket_cleaner/parsing.py:15: return str(value).strip().lower()ticket_cleaner/report.py:38: chosen = sorted({name.strip().lower() for name in categories})La ligne 15 se trouve dans
clean_text(), queclean_category()appelle. La ligne 38 est la deuxième règle. -
Écrivez le test d’abord. Ajoutez-le à la fin de
tests/test_report.py. La fixture (données préparées pour les tests)ticketscontient un billet ouvert de catégorielogin:tests/test_report.py (add at the end) def test_web_form_names_work_in_the_category_option(tickets):summary = build_summary(tickets, [], "open", categories=["Sign-in"])assert summary["by_category"] == {"login": 1}assert summary["categories"] == ["login"] -
Exécutez les tests. Le nouveau test doit échouer pour la raison prévue :
Fenêtre de terminal python -m pytestSortie (extrait) E AssertionError: assert {} == {'login': 1}EE Right contains 1 more item:E {'login': 1}FAILED tests/test_report.py::test_web_form_names_work_in_the_category_option========================= 1 failed, 39 passed in 0.05s ========================= -
Faites le réusinage dans
ticket_cleaner/report.py. Ajoutez une importation en haut et changez une ligne dansbuild_summary():ticket_cleaner/report.py from ticket_cleaner.parsing import clean_categoryfrom ticket_cleaner.records import Rejected, Ticketticket_cleaner/report.py, in build_summary() chosen = sorted({name.strip().lower() for name in categories})chosen = sorted({clean_category(name) for name in categories})Mettez aussi à jour la chaîne de documentation pour qu’elle indique la règle utilisée. Le résultat se trouve dans l’instantané
end-of-m05, si vous voulez comparer :ticket_cleaner/report.py, the docstring of build_summary() """Return the report as a dictionary that can be saved as JSON.With categories, only the tickets in one of them are selected. The names arecleaned as the tickets' categories are (clean_category). The "categories"key is added only then, so the report without it is unchanged.""" -
Exécutez les vérifications :
Fenêtre de terminal python -m pytestruff check .ruff format --check .Output (the end of each command) ============================== 40 passed in 0.04s ==============================All checks passed!21 files already formattedLes 39 anciens tests réussissent encore. Le test de référence de base réussit aussi, donc le rapport sans
--categoryn’a pas changé. -
Relancez la commande de Grace et ouvrez le rapport :
Fenêtre de terminal python -m ticket_cleaner data/web-form-export.csv --category Sign-inLe rapport contient maintenant
"selected": 4,"by_category": {"login": 4}et"categories": ["login"]. Avec--category " LOGIN " --category Invoice, il contient{"billing": 3, "login": 4}. -
Vérifiez la portée, puis faites un commit :
Fenêtre de terminal git diff --statgit add -Agit commit -m "Clean the --category names with the same rule as the tickets"Sortie tests/test_report.py | 6 ++++++ticket_cleaner/report.py | 8 +++++---2 files changed, 11 insertions(+), 3 deletions(-)[feature/category-option 23d515b] Clean the --category names with the same rule as the tickets2 files changed, 11 insertions(+), 3 deletions(-)L’empreinte de votre commit est différente.
Deux fichiers, onze lignes ajoutées. Comparez cela à +40 −21 dans trois fichiers pour « rendre le code plus propre », sans résoudre le problème de Grace.
Soyez honnête sur un point. Strictement, ce changement dépasse le réusinage, parce qu’un comportement change : --category Sign-in trouve maintenant des billets. C’est pourquoi il a reçu un test qui échouait d’abord. Dans la prochaine leçon, il reçoit aussi une ligne dans DECISIONS.md. Un « réusinage » qui change le comportement sans test ni trace écrite est une fonctionnalité cachée.
Ce qu’Amira n’a pas changé
Section intitulée « Ce qu’Amira n’a pas changé »Pendant qu’elle travaillait dans report.py, Amira a vu d’autres choses qu’elle pouvait améliorer. Elle les a toutes notées et n’en a changé aucune :
count_by_category()pourrait utilisercollections.Counter, comme dansrefactor-open. La tâche ne l’exige pas.write_json()pourrait utiliser un fichier temporaire unique. Cela serait peut-être plus sûr, mais change la façon d’enregistrer chaque rapport. Il lui faut sa propre tâche, ses propres tests et un réviseur qui comprend pourquoi c’est important.filter_by_status()compare le statut exactement.--statusaccepte seulementopen(ouvert),pending(en attente) etclosed(fermé). La tâche n’exige donc aucune règle de nettoyage à cet endroit.
Chaque ligne rejoint la liste de tâches de l’équipe, avec une phrase expliquant pourquoi. Si l’équipe est d’accord, chacune devient une petite tâche avec sa propre révision. Rien n’est perdu, et rien n’est mêlé au changement de Grace.
Quand réusiner, et à quel coût
Section intitulée « Quand réusiner, et à quel coût »Réusinez dans une tâche quand le changement serait incorrect ou difficile à ajouter sans cela. La duplication qui donne deux réponses à une question, comme ici, est le cas le plus clair. Une fonction que vous devez changer, mais que vous ne comprenez pas, en est un autre. Renommez-la ou divisez-la d’abord, dans son propre commit. Les tests doivent réussir avant et après.
Ne réusinez pas dans une tâche parce que le code est vieux, que vous l’écririez autrement ou qu’un assistant le propose. Une demande comme « améliorez partout où vous le pouvez » fait de l’assistant le décideur. Avec un assistant, les modifications supplémentaires semblent gratuites, parce que vous ne les avez pas tapées. Elles ne le sont pas. Chacune coûte du temps de révision et peut entrer en conflit avec le travail d’un collègue.
Faites du réusinage une tâche distincte quand il est important ou touche du code utilisé par beaucoup de personnes, comme write_json(). Il reçoit alors sa propre fiche : le comportement à préserver et les tests qui le montrent.
Un réusinage sélectif a aussi un coût. Le code reste un peu moins ordonné qu’il pourrait l’être, et la liste de tâches distinctes s’allonge. C’est un prix raisonnable pour un changement qu’un réviseur peut vérifier en quelques minutes.
Erreur courante
git apply indique qu'un correctif ne s'applique pas
Symptôme : vous gardez un gros réusinage de l’assistant pour plus tard, sous forme de fichier de correctif. Des semaines plus tard, vous essayez de l’appliquer à votre projet :
git apply --check ../nextia-learning-labs/C15/transcripts/refactor-open.patcherror: patch failed: ticket_cleaner/parsing.py:21error: ticket_cleaner/parsing.py: patch does not applyerror: patch failed: ticket_cleaner/report.py:1error: ticket_cleaner/report.py: patch does not applyCause : le correctif a été créé à partir du code de start. Depuis, le module 4 a changé clean_category() dans parsing.py, près de la ligne 21. Cette leçon a aussi ajouté une importation en haut de report.py. Un correctif trouve son emplacement grâce aux lignes qui entourent chaque changement. Ces lignes sont maintenant différentes, donc Git refuse. --check teste seulement le correctif et ne change aucun fichier.
Diagnostic : git apply --stat montre ce que le correctif touche, sans l’appliquer :
ticket_cleaner/files.py | 27 ++++++++++++++++++++------- ticket_cleaner/parsing.py | 28 +++++++++++++++++----------- ticket_cleaner/report.py | 6 +++--- 3 files changed, 40 insertions(+), 21 deletions(-)Solution : ne forcez pas l’application. Un réusinage étendu touche beaucoup de lignes et entre donc en conflit avec presque tout autre changement. Prenez seulement ce qu’une tâche exige. Refaites la demande avec les fichiers actuels et une tâche bien délimitée. C’est le coût caché d’un gros réusinage : dans une équipe, d’autres personnes changent les mêmes fichiers pendant que vous attendez.
À vous de jouer : trier quatre suggestions
Section intitulée « À vous de jouer : trier quatre suggestions »Amira confie à un assistant la tâche liée à Sign-in. Imaginez qu’il propose quatre suggestions. Pour chacune, décidez : la faire dans cette tâche ou la noter comme tâche distincte? Utilisez les deux questions du diagramme et donnez une raison.
- Dans
report.py, appelezclean_category(name)pour les noms de--category. - Renommez
chosenenwanted_categoriesdansbuild_summary(). - Déplacez
CATEGORY_ALIASESderecords.pyversparsing.py, « parce que seulparsing.pyl’utilise ». - Ajoutez la prise en charge de
--categoryà l’entréeremote.
Ensuite, faites une prédiction avant d’exécuter la commande : que sélectionne maintenant --category Delivery dans l’exportation de Grace? Exécutez-la et vérifiez.
Afficher la réponse
- Faites-le dans cette tâche. Le changement en a besoin : sans cela,
--category Sign-inne sélectionne rien. Il change le comportement et exige donc un test qui échoue d’abord. C’est le changement que vous avez fait. - Tâche distincte, ou pas du tout. Un nom plus clair peut aider, mais la tâche fonctionne sans cela. Ce changement ajoute des lignes aux différences que le réviseur doit vérifier.
- Tâche distincte. L’affirmation est vraie : seul
parsing.pyutilise la liste. Mais la tâche fonctionne sans ce déplacement. Le README renvoie àticket_cleaner/records.pypour la liste, et l’équipe du formulaire Web la modifie à cet endroit. Un déplacement changerait leurs habitudes et le README aussi. - Tâche distincte, et inutile.
--categoryfonctionne déjà avecremote:cli.pytransmet l’option àbuild_summary()après la lecture des enregistrements, peu importe leur source. La suggestion repose sur une supposition concernant du code que l’assistant n’a pas lu.
--category Delivery : Delivery est un des noms du formulaire Web, et clean_category() le transforme en shipping. Le rapport contient donc "selected": 2, "by_category": {"shipping": 2} et "categories": ["shipping"]. Avec la règle du module 4, la même commande sélectionnait 0. L’auteur a exécuté les deux versions et obtenu ces résultats.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
La session refactor-open a modifié 3 fichiers (+40 −21), et les 24 tests ont réussi. Pourquoi cela ne suffit-il pas pour l'accepter?
Afficher la réponse
Les tests montrent seulement que rien de ce qu’ils vérifient n’a cessé de fonctionner. La demande « rendre le code plus propre » n’avait aucun critère d’acceptation. Aucun test ne peut donc montrer que le travail est terminé ou correct. Certaines modifications touchent du code important, comme write_json(), qui enregistre chaque rapport, et aucun nouveau test ne les vérifie. Le mot « plus sûr » employé par l’assistant est une affirmation sans preuve. Et le vrai problème, le bogue de Grace dans clean_category(), était toujours là. Chaque modification exige une tâche qui la demande et des preuves qui la justifient.
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
Faites une prédiction : vous remplacez de nouveau clean_category(name) dans report.py par name.strip().lower(). Quels tests échouent, et qu'est-ce que cela vous apprend?
Afficher la réponse
Seul le nouveau test échoue : test_web_form_names_work_in_the_category_option. L’auteur l’a exécuté à la fin du module, avec 42 tests : 1 failed, 41 passed (1 échec, 41 réussites). Les autres tests utilisent des noms que les deux règles nettoient de la même façon, comme " Billing ". Ce test est donc la seule protection du réusinage. Voilà pourquoi vous l’avez écrit d’abord, et pourquoi vous ne devez pas le supprimer comme « redondant ».
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 demande : « Ce changement fait fonctionner Sign-in. C'est donc une fonctionnalité, pas un réusinage. A-t-on enfreint la règle voulant qu'un réusinage ne change pas le comportement? »
Afficher la réponse
Il a raison : le comportement de --category change pour les noms du formulaire Web. On le traite donc comme un changement de comportement. Il reçoit un test qui échoue d’abord, son propre commit (enregistrement des modifications) avec un message clair, et une décision dans DECISIONS.md. Le réusinage est le moyen utilisé : une règle de nettoyage à un seul endroit plutôt que deux. Nommez le changement pour ce qu’il est dans le commit et la demande de tirage, pour éviter toute surprise.
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
- Un réusinage change la structure et conserve le comportement. Réusinez de façon sélective : seulement là où le changement demandé l’exige.
- « Rendre le code plus propre » (cas réel,
refactor-open) a produit cinq modifications qu’aucune tâche ne demandait,+40 −21, tous les tests réussis, et le bogue de Grace inchangé. - Posez deux questions : le changement en a-t-il besoin? Est-ce que cela change le comportement? Si le comportement change, écrivez un test qui échoue d’abord.
- La duplication était la vraie raison ici : deux règles de nettoyage donnaient 0 billet pour
--category Sign-in. Une seule règle,clean_category(), en donne 4. - Notez chaque autre amélioration comme une tâche distincte. Un réusinage étendu prend du temps de révision et entre en conflit avec d’autres travaux.
- Votre projet :
40 passed(40 réussites), et un nouveau commit.
Ensuite, vous notez vos décisions et leurs raisons, pour que la prochaine personne n’ait pas à deviner.
Leçon suivante : Documenter les décisions