Aller au contenu
English

Documenter les décisions

  • Leçon 14
  • 40 min
  • Module 5 : Livrer un travail facile à maintenir

Où nous en sommes

Dans la dernière leçon, nous avons réusiné seulement ce que la modification exigeait, et noté les autres idées comme des tâches distinctes. Mais la personne suivante ne peut pas voir pourquoi le code est construit ainsi, ni ce qu'il ne peut pas faire, et le résumé d'un assistant est une affirmation, pas une preuve. Dans cette leçon, nous écrivons le README et un registre des décisions, avec une preuve pour chaque affirmation, comme une note dans la marge d'une fiche de recette.

Ce que vous saurez faire

Notez comment utiliser le projet, ce qu’il ne peut pas faire et pourquoi il est construit ainsi. Placez chaque fait à un seul endroit. Donnez une preuve pour chaque affirmation : un test, une commande exécutée ou le nom de la personne qui doit la vérifier.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 40 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Le projet ~/projects/ticket-cleaner-assist après la dernière leçon, avec son environnement actif. python -m pytest affiche 40 passed (40 tests réussis), et git status --short n’affiche rien.
  • Le dossier d’exercices ~/projects/nextia-learning-labs, avec C15/snapshots/end-of-m05/.
  • Si le projet manque ou ne fonctionne plus, suivez les étapes de réinitialisation sous Vérification du module, puis refaites la dernière leçon.

Une fiche de recette familiale pour un gâteau indique « 100 g de sucre ». Dans la marge, au crayon : « Pas 200 : les enfants le trouvaient trop sucré. Le miel brûle, ne l’utilisez pas. »

Des années plus tard, quelqu’un prépare ce gâteau pour la première fois. Sans la note, cette personne pourrait croire que 100 g est une faute de frappe et en utiliser 200. Ou elle pourrait essayer le miel, parce qu’il semble meilleur pour la santé. La note lui évite de répéter deux anciens essais. Elle explique aussi pourquoi, pour permettre de revoir le choix si la raison change.

Une recette sans note fonctionne. Une recette avec une note erronée est pire qu’une recette sans note. « Cuire pendant 20 minutes », alors que le gâteau en demande 40, mène à un échec malgré la confiance accordée.

Le problème : des documents que personne n’a vérifiés

Section intitulée « Le problème : des documents que personne n’a vérifiés »

Regardez un paragraphe de README.md dans votre projet. Il accompagnait la modification du collègue dans l’instantané start :

README.md (the paragraph that came with the teammate's change)
The new web form uses other names for some categories, for example `Sign-in` and `Invoice`. The report counts them under its own names (`login`, `billing`); `ticket_cleaner/records.py` lists them.

Chaque mot est vrai pour les deux exemples. Mais le lecteur comprend « une ligne par équipe ». L’exportation de Grace avait trois lignes pour une équipe : LOGIN, Login et login. Personne n’a comparé la promesse du README à l’exportation, et aucun test ne l’a fait non plus. Le document semblait terminé, alors personne n’a posé de question.

Un assistant augmente ce risque d’erreur, parce qu’il rédige des résumés avec assurance. Dans la session refactor-open, il a dit qu’il allait « rendre les écritures JSON plus sûres ». C’est peut-être vrai. Mais rien dans la session ne l’a mesuré, et aucun test ne le vérifie. Copiez cette phrase dans un document, et le document contient maintenant une affirmation que personne n’a vérifiée.

Le problème inverse est tout aussi réel : une décision sans trace écrite. Tomás lit la limite du README concernant biling, et il a une idée :

« Ajoutons un paquet de correspondance approximative, pour que biling compte comme billing. Une ligne, et le rapport est plus propre. »

Amira a deux raisons de s’y opposer. Le rapport ne doit pas deviner, parce qu’une mauvaise supposition transfère un billet de soutien à une autre équipe. Et dans Vérifier les dépendances, un paquet de correspondance approximative avait déjà échoué à la question « est-il nécessaire? ». Si ces raisons restent seulement dans sa mémoire, l’équipe reprend la même discussion tous les quelques mois. Ou quelqu’un ajoute le paquet pendant ses vacances.

L’idée : deux fichiers, deux fonctions et une preuve pour chaque affirmation

Section intitulée « L’idée : deux fichiers, deux fonctions et une preuve pour chaque affirmation »

Un projet a besoin de deux types de documentation, pour deux types de lecteurs :

  • Le README explique à un utilisateur ou à un nouveau développeur ce que fait le projet, comment le configurer et l’exécuter. Il dit aussi ce que le projet ne peut pas faire. Une limite décrit clairement ce que le projet ne fait pas, pour que personne ne compte dessus.
  • Un registre de décisions explique au prochain développeur pourquoi le projet est construit ainsi. Chaque entrée présente le choix, la raison, la vérification effectuée et les solutions rejetées. Beaucoup d’équipes appellent ces entrées des registres de décisions d’architecture. Dans ticket-cleaner, elles forment un court fichier, DECISIONS.md.

Une règle s’applique aux deux : n’écrivez aucune affirmation que vous n’avez pas vérifiée. Chaque phrase qui décrit ce que fait le programme doit avoir une preuve. Un test est la meilleure preuve, parce qu’il revérifie l’affirmation après chaque modification. Une commande exécutée constitue une bonne preuve pour une affirmation qui change rarement. Et quand seule une personne peut vérifier une affirmation, indiquez son nom.

Un tableau de cinq endroits où documenter ticket-cleaner. README.md : comment configurer, exécuter et utiliser le programme, et ce qu'il ne peut pas faire, pour les utilisateurs et les nouveaux développeurs; exemple, la limite selon laquelle un nom de catégorie avec une faute de frappe, biling, forme une catégorie distincte. DECISIONS.md : pourquoi, chaque choix important, sa vérification et les solutions rejetées, pour la prochaine personne qui modifie le code; exemple, décision 3, les noms de catégories sont nettoyés à un seul endroit, vérifié par test_web_form_names_work_in_the_category_option. docs/tasks : ce qui a été demandé, la fiche avec ses critères et le rapport de bogue; exemple, category-option.md avec 7 critères d'acceptation. Messages de commit : ce qu'une étape a modifié; exemple, nettoyer les noms de --category avec la même règle que les billets. Chaînes de documentation : ce qu'une fonction promet; exemple, les noms sont nettoyés comme les catégories des billets.
Chaque type de connaissance a sa place. Le README contient un lien vers DECISIONS.md; il ne le copie pas.
Description textuelle du diagramme

Cinq endroits, chacun avec une fonction :

  • README.md : comment configurer, exécuter et utiliser le programme, et ce qu’il ne peut pas faire. Pour les utilisateurs et les nouveaux développeurs.
  • DECISIONS.md : pourquoi. Chaque choix important, sa vérification et les solutions rejetées.
  • docs/tasks/ : ce qui a été demandé. La fiche avec ses critères et le rapport de bogue.
  • Messages de commit : ce qu’une étape a modifié.
  • Chaînes de documentation : ce qu’une fonction promet.

Placez un fait à un seul endroit, et créez des liens vers celui-ci depuis les autres. Deux copies d’un fait finissent par diverger.

Un petit exemple : une décision, chaque partie visible

Section intitulée « Un petit exemple : une décision, chaque partie visible »

Voici la décision 3 de DECISIONS.md, sur la modification de la dernière leçon. Lisez-la en quatre parties :

DECISIONS.md (decision 3)
## 3. Category names are cleaned in one place
`clean_category` (`ticket_cleaner/parsing.py`) cleans a category in the same
way as the status and the ID: no spaces around it, small letters. Then it
changes the web form's names to ours. `--category` uses the same function, so
`--category Sign-in` selects the login tickets.
- Grace's bug: `clean_category` looked up the alias in small letters but kept
the original text for other names, so `LOGIN` and `login` were two
categories. The fix is one line: clean the text first.
- Checked by: `test_capital_letters_do_not_make_a_new_category` (it fails on
the code before the fix), `test_web_form_export_has_one_line_per_team` and
`test_web_form_names_work_in_the_category_option`.
  1. Le choix, dans le titre : un seul endroit pour la règle de nettoyage.
  2. La raison : le statut et l’identifiant sont nettoyés de la même façon, et une deuxième règle a causé le bogue de Grace.
  3. La preuve : trois tests, nommés. N’importe qui peut les exécuter : python -m pytest -k web_form_names_work affiche 1 passed, 41 deselected (1 test réussi, 41 non sélectionnés).
  4. La solution rejetée : la décision 3 n’en a aucune, parce que personne n’en a proposé. Les décisions 1, 2 et 4 nomment chacune une proposition rejetée du module 3, avec la raison.

La lecture prend deux minutes. Il faudrait une heure pour retrouver ces informations dans le code et l’historique.

Amira rédige les documents en dernier, quand le code est final. Sinon, elle documente des éléments qui changent encore. Elle commence aussi par un test, pour que le README ne diverge pas sans que quelqu’un le remarque.

  1. Rendez le README vérifiable. Copiez le test du README depuis l’instantané, et lisez-le :

    Fenêtre de terminal
    cp ../nextia-learning-labs/C15/snapshots/end-of-m05/tests/test_readme.py tests/
    tests/test_readme.py
    """The README's claims are checked, so that it stays true after a change."""
    import re
    from pathlib import Path
    from ticket_cleaner.cli import main, make_parser
    README = Path("README.md").read_text(encoding="utf-8")
    def test_the_readme_shows_the_real_output(tmp_path, capsys):
    assert main(["data/tickets.csv", "--output", str(tmp_path / "s.json")]) == 0
    first_line = capsys.readouterr().out.splitlines()[0]
    assert first_line == "15 rows: 9 valid, 6 rejected."
    assert first_line in README
    def test_every_option_of_the_command_is_in_the_readme():
    options = set(re.findall(r"--[a-z-]+", make_parser().format_help()))
    options.discard("--help")
    documented = set(re.findall(r"^\| `(--[a-z-]+)`", README, re.MULTILINE))
    assert options == documented

    Le premier test exécute le programme et vérifie que le README montre sa véritable première ligne. Le second compare les options de --help aux lignes du tableau des options du README.

  2. Exécutez-le :

    Fenêtre de terminal
    python -m pytest tests/test_readme.py -v
    Output (the end)
    tests/test_readme.py::test_the_readme_shows_the_real_output PASSED [ 50%]
    tests/test_readme.py::test_every_option_of_the_command_is_in_the_readme PASSED [100%]
    ============================== 2 passed in 0.03s ===============================
  3. Voyez-le détecter un écart. Dans votre éditeur, supprimez la ligne --category du tableau des options dans README.md, et enregistrez. Prédisez le résultat, puis relancez le test :

    Fenêtre de terminal
    python -m pytest tests/test_readme.py
    Sortie (extrait)
    E AssertionError: assert {'--category'...', '--status'} == {'--output', '--status'}
    E
    E Extra items in the left set:
    E '--category'
    FAILED tests/test_readme.py::test_every_option_of_the_command_is_in_the_readme
    ========================= 1 failed, 1 passed in 0.03s ==========================

    « L’ensemble de gauche » représente les options de --help. Remettez la ligne :

    Fenêtre de terminal
    git restore README.md
  4. Mettez le README à jour. Faites quatre modifications, et vérifiez chaque affirmation avant de l’écrire. Les différences les montrent :

    git diff README.md (part)
    The new web form uses other names for some categories, for example `Sign-in` and `Invoice`. The report counts them under its own names (`login`, `billing`); `ticket_cleaner/records.py` lists them.
    Categories are counted in small letters, without spaces around them: `LOGIN`, `Login` and `login` are one category. The new web form uses other names for some categories, for example `Sign-in` and `Invoice`. The report counts them under its own names (`login`, `billing`); `ticket_cleaner/records.py` lists them. `--category` cleans the names that you give in the same way, so `--category Sign-in` selects the login tickets.
    git diff README.md (part)
    ## Limitations
    +- A category name with a typing mistake (`biling`) is a category of its own. The report does not guess what was meant.
    +- `--category` with a name that no ticket has gives an empty selection, not an error.
    +- The list of the web form's names is in `ticket_cleaner/records.py`. A new name on the form needs a new line there.
    `DECISIONS.md` explains the main choices.

    Les deux autres modifications sont petites. Une phrase sur ASSISTANT-SCOPE.md va sous « Work on the code » (travailler sur le code). Quatre nouvelles lignes vont dans « Project layout » (structure du projet) : docs/, ASSISTANT-SCOPE.md, DECISIONS.md et LICENSE. Pour éviter de tout retaper, copiez le README depuis l’instantané, puis lisez git diff README.md ligne par ligne :

    Fenêtre de terminal
    cp ../nextia-learning-labs/C15/snapshots/end-of-m05/README.md .
  5. Vérifiez les limites avec de vraies commandes, pas de mémoire :

    Fenêtre de terminal
    python -m ticket_cleaner data/web-form-export.csv --category biling

    Le code de sortie est 0, et le rapport contient "selected": 0, "by_category": {} et "categories": ["biling"]. Les deux premières limites sont vraies. Vérifiez ensuite la troisième :

    Fenêtre de terminal
    python -c "from ticket_cleaner.parsing import clean_category; print(clean_category('Log in'), clean_category('Log-In'), clean_category('Signin'))"
    Sortie
    log in login signin

    Log-In est dans la liste, donc il devient login. Log in avec une espace et Signin n’y sont pas, donc chacun formerait une catégorie distincte. La troisième limite dit exactement cela : un nouveau nom exige une nouvelle ligne.

  6. Ajoutez le registre de décisions. Copiez DECISIONS.md depuis l’instantané, et lisez-le au complet. Il contient cinq décisions et une liste de questions ouvertes :

    Fenêtre de terminal
    cp ../nextia-learning-labs/C15/snapshots/end-of-m05/DECISIONS.md .
    Décision La solution rejetée
    1. --category filtre la sélection, pas le fichier proposition C, qui filtrait avant le résumé
    2. Le rapport sans --category reste exactement identique proposition A, avec "category": null dans chaque rapport
    3. Les noms de catégories sont nettoyés à un seul endroit aucune
    4. Aucune nouvelle dépendance proposition D, avec Unidecode
    5. Non fait, volontairement correspondance approximative, avertissement pour une catégorie inconnue, option --clean

    La dernière section, « Still needs a human review » (nécessite encore une révision humaine), liste ce qu’aucun test ne peut vérifier : la liste des alias et les exportations réelles.

  7. Exécutez chaque test nommé dans DECISIONS.md. -k sélectionne les tests dont le nom contient l’un des mots :

    Fenêtre de terminal
    python -m pytest -v -k "whole_file_counts or report_for_some_categories or baseline or categories_key_only or capital_letters or one_line_per_team or web_form_names_work"
    Output (the end)
    ======================= 9 passed, 33 deselected in 0.03s =======================

    Chaque test nommé existe, et chacun réussit. Une affirmation « vérifié par » est maintenant vérifiée.

  8. Exécutez toutes les vérifications, et faites un commit des trois fichiers :

    Fenêtre de terminal
    python -m pytest
    ruff check .
    ruff format --check .
    git add -A
    git commit -m "Document the cleaning rule, the limitations and the decisions"
    Output (the end of each command)
    ============================== 42 passed in 0.04s ==============================
    All checks passed!
    23 files already formatted
    [feature/category-option 51b4ddf] Document the cleaning rule, the limitations and the decisions
    3 files changed, 104 insertions(+), 1 deletion(-)
    create mode 100644 DECISIONS.md
    create mode 100644 tests/test_readme.py

    Votre empreinte de commit est différente. ruff format --check . compte maintenant 23 fichiers, pas 21 : ruff compte aussi les fichiers Markdown, donc tests/test_readme.py et DECISIONS.md en ajoutent un chacun.

Associez maintenant chaque affirmation des deux documents à sa preuve :

Un tableau de sept affirmations, leur emplacement et leur preuve. LOGIN, Login et login forment une seule catégorie : README Run et DECISIONS décision 3; preuve test_capital_letters_do_not_make_a_new_category, qui échoue avec le code avant la correction. --category Sign-in sélectionne les billets login : README et DECISIONS 3; test_web_form_names_work_in_the_category_option. Chaque option figure dans le tableau des options : README; test_every_option_of_the_command_is_in_the_readme, qui échoue quand une ligne est supprimée. 15 lignes : 9 valides, 6 rejetées : README; test_the_readme_shows_the_real_output. Une faute de frappe, biling, forme une catégorie distincte : README Limitations; une commande, --category biling donne selected 0 et un code de sortie de 0. En orange : la liste des alias correspond au formulaire Web, DECISIONS Still needs a human review; aucun test ne peut le vérifier, l'équipe de Grace est responsable du formulaire. En rouge : les écritures JSON sont plus sûres, résumé d'un assistant; écrit nulle part, parce qu'aucun test ni aucune mesure ne le vérifie.
Chaque affirmation a un test, une commande ou une personne nommée. La seule affirmation sans preuve n'a pas été incluse dans les documents.
Description textuelle du diagramme

Sept affirmations et leurs preuves :

  • « LOGIN, Login et login forment une seule catégorie » : test_capital_letters_do_not_make_a_new_category, qui échoue avec le code avant la correction.
  • « --category Sign-in sélectionne les billets login » : test_web_form_names_work_in_the_category_option.
  • « Chaque option figure dans le tableau des options » : test_every_option_of_the_command_is_in_the_readme, qui échoue quand une ligne est supprimée.
  • « 15 rows: 9 valid, 6 rejected. (15 lignes : 9 valides, 6 rejetées.) » : test_the_readme_shows_the_real_output.
  • « Une faute de frappe (biling) forme une catégorie distincte » : une commande, --category biling → selected (sélectionnés) 0, code de sortie 0.
  • « La liste des alias correspond au formulaire Web » : aucun test ne peut le vérifier. L’équipe de Grace est responsable du formulaire, donc cette affirmation figure sous « Still needs a human review ».
  • « Les écritures JSON sont plus sûres », dans le résumé d’un assistant : aucune preuve, donc aucun document ne la contient.

Consignez une décision quand une personne raisonnable pourrait choisir autrement, ou l’a déjà proposé. Chaque proposition rejetée du module 3 est un tel cas. Chaque chose que vous avez choisi de ne pas faire l’est aussi. Ne consignez pas les décisions que personne ne remettrait en question, comme « nous utilisons pytest ». Un fichier de décisions qui liste tout est aussi difficile à utiliser que l’absence de fichier.

Mettez le README à jour dans le même commit que la modification qu’il décrit. Un README en retard d’un commit est erroné pour ce commit. Quand une affirmation peut devenir un test, faites-en un test, comme dans tests/test_readme.py. Un test ne peut pas vérifier chaque phrase, mais il détecte les écarts les plus courants : une nouvelle option ou une ligne de sortie modifiée.

Ne documentez pas ce que vous n’avez pas vérifié. Si un assistant rédige une section du README, traitez chaque phrase comme une affirmation dans les différences. Vérifiez-la, supprimez-la ou déplacez-la sous « Still needs a human review » avec un nom.

Le coût est réel. Les documents prennent du temps à rédiger, et chaque affirmation conservée doit rester vraie. C’est pourquoi les documents ici sont courts : cinq décisions, trois limites. Les documents courts sont lus et tenus à jour.

Erreur courante

DECISIONS.md nomme un test qui n'existe pas

Symptôme : une décision dit « Vérifié par : test_category_option_accepts_web_form_names ». Vous l’exécutez par son nom, et pytest n’exécute rien :

Fenêtre de terminal
python -m pytest -k test_category_option_accepts_web_form_names
Output (the end)
collected 42 items / 42 deselected / 0 selected
============================ 42 deselected in 0.06s ============================

Le code de sortie est 5 : pytest n’a trouvé aucun test à exécuter. Il n’a affiché aucune erreur en rouge, donc c’est facile à manquer.

Cause : le test a été renommé, ou il n’a jamais été écrit. Un assistant peut aussi inventer un nom de test qui semble correct. Dans les deux cas, la décision cite maintenant une preuve qui n’existe pas.

Diagnostic : listez les tests avec leurs noms, et recherchez les mots :

Fenêtre de terminal
python -m pytest --collect-only -q

Correction : mettez le vrai nom dans DECISIONS.md, ici test_web_form_names_work_in_the_category_option. Puis exécutez-le par son nom : 1 passed, 41 deselected. Faites cela pour chaque nom chaque fois que vous modifiez le fichier, comme à l’étape 7.

Imaginez qu’un assistant a rédigé ce paragraphe pour le README (construit pour le cours). Avant de l’accepter, classez chacune de ses quatre phrases : vérifiée par un test, vérifiée par une commande, nécessite une personne ou fausse. Exécutez des commandes pour décider.

A draft paragraph (constructed)
Category names are cleaned, so every spelling of a team becomes one category.
--category accepts the web form's names, such as Sign-in and Invoice.
The cleaning is fully tested.
A misspelt category, such as biling, is corrected automatically.

Rédigez ensuite une nouvelle entrée pour DECISIONS.md : la proposition de Tomás d’un paquet de correspondance approximative pour biling. Utilisez les quatre parties : le choix, la raison, la preuve et la solution rejetée.

Afficher une solution détaillée
  1. Fausse. clean_category('Log in') donne 'log in', une catégorie distincte. Seules les graphies de la liste deviennent une seule catégorie. Écrivez plutôt : « Les majuscules et les espaces autour d’un nom ne comptent pas, et les noms du formulaire Web dans records.py deviennent les nôtres. »
  2. Vérifiée par un test. test_web_form_names_work_in_the_category_option vérifie Sign-in. La commande --category Invoice sélectionne 3 billets de facturation dans l’exportation de Grace.
  3. Ce n’est pas une affirmation vérifiable. « Entièrement testé » n’a aucune mesure. Supprimez-la, ou nommez ce que les tests couvrent.
  4. Fausse. --category biling donne "selected": 0. La limite du README dit le contraire, et c’est elle qui est vraie.

Une entrée possible :

DECISIONS.md (a possible entry)
## 6. Misspelt categories are not corrected
A misspelt category (`biling`) stays a category of its own. The report must
not guess: a wrong guess moves a ticket to another team, and nobody sees it.
A separate line shows the mistake, and Grace's team can fix the source.
- Checked by: `python -m ticket_cleaner data/web-form-export.csv --category
biling` gives `"selected": 0`, exit code 0.
- Rejected: a fuzzy-matching package (proposed by Tomás). It guesses, it is a
new dependency, and the alias list in `records.py` already handles the
known names.

La décision 5 de l’instantané dit déjà « Aucune correspondance approximative », en une ligne. Votre entrée plus longue convient pour vous exercer. Dans le projet, ajoutez la raison à la décision 5 plutôt qu’une deuxième entrée pour le même choix.

Vérifiez votre compréhension

Quelle différence y a-t-il entre le rôle de README.md et celui de DECISIONS.md? Donnez une phrase de chaque fichier de ticket-cleaner qui ne pourrait pas aller dans l'autre.

Afficher la réponse

Le README explique comment préparer, exécuter et utiliser le programme, et ce qu’il ne peut pas faire. DECISIONS.md explique au prochain développeur pourquoi le programme est construit ainsi, comment chaque choix a été vérifié et ce qui a été rejeté. « Un nom de catégorie avec une faute de frappe (biling) constitue une catégorie distincte » appartient au README. L’utilisateur en a besoin pour lire le rapport. « Rejeté : une modification proposée qui retirait les billets des autres catégories dans cli.py, avant le résumé » appartient à DECISIONS.md. L’utilisateur n’en a pas besoin, mais le développeur qui veut modifier le filtre, oui.

Vérifiez votre compréhension

Le README de start disait que le rapport compte les noms du formulaire Web sous leurs propres noms. Chaque mot était vrai. Pourquoi était-ce quand même un problème, et qu'est-ce qui l'aurait détecté?

Afficher la réponse

Le lecteur comprend « une ligne par équipe », ce qui était faux : l’exportation de Grace présentait LOGIN, Login et login sur trois lignes. L’affirmation était vraie seulement pour les exemples mentionnés. Un test exécutant le programme sur une exportation contenant différentes graphies aurait détecté le problème. Ce test existe maintenant : test_web_form_export_has_one_line_per_team. Sans un tel test, un document est une promesse que personne ne continue de vérifier.

Vérifiez votre compréhension

Faites une prédiction : vous ajoutez une option --since à la commande, mais vous ne modifiez pas le README. Quel test échoue, et avec quel message?

Afficher la réponse

test_every_option_of_the_command_is_in_the_readme échoue. Les options de --help (aide) contiennent maintenant --since, mais pas le tableau du README. pytest signale la différence par « Extra items in the left set » (éléments supplémentaires dans l’ensemble de gauche), avec '--since', comme pour --category à l’étape 3. Le test vérifie seulement la présence de la description de l’option, pas son exactitude. Vous devez toujours comparer votre propre phrase au code.

Récapitulatif

  • Le README explique comment utiliser le projet et ce qu’il ne peut pas faire (ses limites). Un registre des décisions, DECISIONS.md, explique pourquoi : le choix, la raison, les preuves et les autres solutions rejetées.
  • N’écrivez aucune affirmation que vous n’avez pas vérifiée. Une preuve est un test, une commande que vous avez exécutée, ou une personne nommée sous « Still needs a human review » (nécessite encore une révision humaine).
  • Le résumé d’un assistant est une affirmation, pas une preuve. « Plus sûr » sans mesure n’a pas sa place dans les documents.
  • tests/test_readme.py garde deux affirmations du README vraies après chaque modification. Exécutez chaque test nommé dans DECISIONS.md, en utilisant son nom.
  • Votre projet : 42 passed (42 tests réussis), avec le README, DECISIONS.md et le test du README dans un seul commit (enregistrement des modifications).

Ensuite, vous expliquez chaque ligne importante de l’ensemble des modifications. Vous ouvrez une demande de tirage (pull request) qu’un réviseur peut vérifier sans vous.

Leçon suivante : Comprendre le code par vous-même