README + Run met één commando
Je hebt een strakke lay-out en echte tests. De laatste mijl is het deel waar reviewers als eerste op klikken: de README en de ene opdracht die het ding uitvoert. Een project dat tien minuten gokken kost om te starten voelt kapot zelfs als het werkt. Een project dat je kunt clonen en uitvoeren met één regel voelt professioneel zelfs als het klein is. Dezelfde code -> totaal andere indruk.
De README is een contract. Een lezer scant het van boven naar beneden en verwacht een voorspelbare vorm: de naam van het project als titel, dan hoe je het installeert, dan hoe je het gebruikt, dan hoe je het test. Concreet heeft een sterke README een titel op het hoogste niveau (# Something), dan deze secties in deze volgorde:
# Triage Copilot
## Setup
pip install -e . # editable install
cp .env.example .env # then paste your real key into .env
## Usage
python -m triage # the one-command run
## Tests
pytest
Volgorde is belangrijk omdat een lezer het als stappen volgt. Gebruik voor Setup is verwarrend -> je kunt niet gebruiken wat je niet hebt geïnstalleerd. Dus schrijf je een checker, validate_readme(text), die True alleen teruggeeft als een # titel verschijnt, gevolgd door ## Setup, dan ## Usage, dan ## Tests, elk na het vorige. Een ontbrekende sectie, of secties in de verkeerde volgorde, geeft False terug. De truc: loop de regels één keer door, houd een "cursor" bij van waar je bent, en eis dat elke sectie verschijnt op een positie after de cursor.
De run met één commando. Let op dat de ## Usage regel hierboven een enkel commando is. Dat is het doel van een Makefile of justfile target zoals make run -> één memorabel commando dat het project start, zodat niemand de volledige aanroep moet onthouden. Schrijf make_run(name) dat die commando-string voor een project teruggeeft, bijvoorbeeld python -m triage (of make run). Het moet de projectnaam bevatten, genormaliseerd op dezelfde manier als de pakketmap, zodat een ander project een ander commando oplevert.
Twee eerlijke, niet-beoordeelde noten voor de echte repo. Eerst, geheimen: de cp .env.example .env step bestaat omdat je echte API-key in .env gaat, die je toevoegt aan .gitignore en never commit. Je commit alleen .env.example -> de shape van de config met placeholder-waarden. Het lekken van een key naar een publieke repo is de klassieke portfolio-project fout. Ten tweede, deploying this: om het online te zetten zou je een kleine Dockerfile schrijven (kopieer de repo, pip install, stel de run command in als entrypoint) en pushen naar een PaaS zoals Render, Railway of Fly. Dat deel kan niet worden uitgevoerd of beoordeeld in je browser -> het is voor jou om te doen wanneer je publiceert. Druk op Run om een volledige README te valideren en de run command af te drukken.
Schrijf de twee deterministische delen van een goede README. validate_readme(text) geeft True terug als een # titel op het hoogste niveau verschijnt, dan ## Setup, dan ## Usage, dan ## Tests, elk na het vorige (een ontbrekende sectie of secties in de verkeerde volgorde -> False). make_run(name) geeft de run-string van één opdracht terug (bijv. python -m <pkg> of make run) die de projectnaam bevat, genormaliseerd zoals de package dir, zodat een andere naam een andere opdracht oplevert.
Een probleem ontdekt in deze les? Meld het · Vraag naar deze les
Deze oefening opent binnenkort
Maak de les ervoor af voordat deze wordt ontgrendeld. De hele cursus is gratis, geen account nodig, en je kunt deze les nu lezen.
Deze browser blokkeert cookies voor learn.floati.life, dus lessen die je hier hebt afgerond kunnen niet in de juiste volgorde worden geopend. Sta cookies toe voor deze site en laad de pagina opnieuw.