Neem het project mee

Het hulpmiddel is af. In deze les draag je het over aan iemand anders.

Dat is een andere taak dan het werkend krijgen, en daar heeft deze hele cursus naartoe gewerkt. Hoofdstuk 12 deed het voor de API-client. Dit is dezelfde oefening met meer onderdelen: twee testmodules, twee dependencyrecepten, een offline gegevensbestand en een commando met zes gedragingen.

Schrijf de README die je zelf zou willen krijgen

Stel je iemand voor die je tien bestanden heeft, nooit met je heeft gesproken en Python heeft geïnstalleerd. Wat heeft die nodig?

Begin met twee zinnen over wat het hulpmiddel is. Daarna de installatie, zonder activering precies zoals in hoofdstuk 12, zodat die in elke shell werkt zonder dat iemand aan activeren hoeft te denken:

python3 -m venv .venv
./.venv/bin/python -m pip install -r requirements-dev.txt
./.venv/bin/python -m pytest -q

Daarna het PowerShell-equivalent en vervolgens de commando’s die het hulpmiddel echt uitvoeren. Zeg dat Python 3.10 of nieuwer vereist is en dat iemand die alleen het programma wil uitvoeren requirements.txt installeert in plaats van het ontwikkelrecept.

Documenteer de interface: het positionele rapportpad, elke optie met de standaardwaarde en het feit dat --refresh en --offline-source niet samen kunnen. Iemand die je README leest, hoort zonder uitvoeren te kunnen voorspellen wat een commando doet.

Wees eerlijk over de API

Eén ding mag je niet weglaten, en het is het lastige punt.

De oefen-API staat binnen Python Land. Zodra dit project op de computer van iemand anders staat, werkt de netwerkroute niet. Elk commando dat probeert op te halen zal mislukken.

Zeg dat helder, ergens bovenaan. Zeg daarna wat nog wel werkt: de volledige testsuite, omdat die namaakantwoorden gebruikt, en de offlinemodus, omdat die een bestand leest dat je hebt meegeleverd.

./.venv/bin/python practice_report.py offline-report.txt --offline-source data/offline-page.json
./.venv/bin/python -m pytest -q

Documentatie die een bekende beperking stilletjes weglaat, is slechter dan documentatie die er een toegeeft. De lezer ontdekt die binnen een paar minuten en gaat dan ook twijfelen aan al het andere dat je schreef.

Voer daarna je eigen instructies uit

Sla eerst je voltooide README op en gebruik daarna Download project terwijl je bent ingelogd. Bewaar de ZIP en pak die uit in een nieuwe lokale map. Open een terminal in die uitgepakte projecthoofdmap.

Volg daar je README vanaf het begin, zonder iets over te slaan en zonder kennis te gebruiken die alleen in je hoofd zit. Als je de route kiest waarbij je alleen op de site werkt, lees de handleiding dan hier na en kies die route in de laatste les.

Je zult iets vinden. Bijna iedereen doet dat: een commando dat een map veronderstelt waar je nooit naartoe liet gaan, een stap die alleen werkt omdat je omgeving al klaarstond of een vlag die op verschillende plekken anders gespeld is.

Die ontdekking is precies het doel van de oefening.

Voer het commando voor het offlinerapport uit vóór het controleprogramma in de volgende les, want het gegenereerde offline-report.txt is een van de dingen die dat programma bekijkt.

./.venv/bin/python practice_report.py offline-report.txt --offline-source data/offline-page.json

offline-report.txt staat niet in de download en hoort daar ook niet in. Het commando maakt het in het uitgepakte project, waar het lokale controleprogramma uit de laatste les het leest.

Vraag Monty je README te lezen als iemand die het project nooit eerder zag en de eerste instructie aan te wijzen die iets veronderstelt dat je nooit hebt opgeschreven.