Die README nennt eine Funktion, die fehlt
Ein Assistent schreibt in Sekunden eine README oder Kommentare zu Ihrem Code. Der Text klingt sicher und liest sich gut.
Er kann aber Funktionen nennen, die es nicht gibt, oder ein Verhalten beschreiben, das der Code nicht hat. Diese Lektion zeigt, wie Sie jede Aussage der Dokumentation gegen den Code prüfen.
Am Ende dieser Lektion
Notiz
Ich kann einen Assistenten eine Dokumentation schreiben lassen und jede Behauptung darin gegen den Code prüfen.
Schlüsselwörter
| Begriff | Was er bedeutet | Beispiel |
|---|---|---|
| Dokumentation | Text, der sagt, was Code tut und wie man ihn benutzt | |
| Behauptung | eine Aussage der Dokumentation, die der Code stützen muss | summe(buch) |
| Beleg | die Stelle im Code, die eine Behauptung stützt | |
| Warum-Kommentar | ein Kommentar, der den Grund nennt und nicht die Tat | |
| README | die Datei, die ein Projekt in einer Seite erklärt |
Die Zellen, die Lernende ausfüllen, bleiben in dieser Vorschau leer.
Jede Aussage der Dokumentation ist eine Behauptung
Eine Dokumentation besteht aus Behauptungen: Diese Funktion gibt es, sie nimmt zwei Parameter, sie ändert das Buch nicht. Ein Assistent schreibt sie nach dem, was wahrscheinlich klingt, nicht nach dem, was im Code steht.
Prüfen Sie darum jede Behauptung an einem Beleg im Code. Findet sich keiner, streichen Sie die Behauptung oder ändern Sie den Code bewusst.
Ein Kommentar soll das Warum nennen
Ein Kommentar wie „addiert eins zu i“ wiederholt, was der Code schon sagt. Er veraltet, sobald der Code sich ändert, und niemand merkt es. Ein Warum-Kommentar nennt den Grund: „Die Zählung beginnt bei eins, weil Kassenzettel so nummeriert sind.“
Bitten Sie den Assistenten ausdrücklich um das Warum, und streichen Sie, was nur wiederholt.
Eine mögliche Anfrage an den Assistenten
So könnte eine Anfrage lauten: „Schreibe eine README für kassenbuch.js. Nenne nur Funktionen, die in der Datei stehen, mit ihren Parametern. Beschreibe nur, was der Code tut, nicht was er tun könnte.“
Was zurückkommt, ist jedes Mal anders. Lesen Sie jede Zeile als Behauptung und suchen Sie ihren Beleg.
Eine Dokumentation gegen den Code halten
Die Runs unten schreiben in einen Ordner demo-doku/ ein kleines Kassenbuch, eine Dokumentation dazu und ein Skript, das jeden genannten Namen im Code sucht. Alles ist von Hand geschrieben und keine Antwort eines Assistenten.
Die Dokumentation nennt vier Funktionen. Eine davon gibt es nicht.
Den Code des Kassenbuchs schreiben
docker exec -w /home/node/project agent sh -c "mkdir -p demo-doku && printf '%s\n' '// Kassenbuch: Betraege in Cent in einer Liste.' 'function buche(buch, betrag) {' ' buch.push(betrag);' ' return buch;' '}' 'function storniere(buch, betrag) {' ' const rest = [];' ' for (const b of buch) {' ' if (b === betrag) continue;' ' rest.push(b);' ' }' ' return rest;' '}' 'function summe(buch) {' ' let s = 0;' ' for (const b of buch) s = s + b;' ' return s;' '}' 'module.exports = { buche, storniere, summe };' > demo-doku/kassenbuch.js"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Die Dokumentation schreiben
docker exec -w /home/node/project agent sh -c "mkdir -p demo-doku && printf '%s\n' '# Kassenbuch' 'Ein Kassenbuch ist eine Liste von Beträgen in Cent.' 'buche(buch, betrag) gibt ein neues Buch zurück, das alte bleibt unverändert.' 'storniere(buch, betrag) entfernt genau einen Eintrag.' 'summe(buch) gibt die Summe aller Beträge zurück.' 'tagesabschluss(buch) schreibt die Summe in eine Datei.' > demo-doku/LIESMICH.md"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Das Skript für die Namen schreiben
docker exec -w /home/node/project agent sh -c "mkdir -p demo-doku && printf '%s\n' 'const fs = require(\"fs\");' 'const code = require(\"./kassenbuch.js\");' 'const namen = [];' 'for (const zeile of fs.readFileSync(\"LIESMICH.md\", \"utf8\").split(\"\n\")) {' ' const treffer = zeile.match(/[a-z_]+[(]/g);' ' if (treffer === null) continue;' ' for (const t of treffer) namen.push(t.slice(0, t.length - 1));' '}' 'let fehlen = 0;' 'for (const name of namen) {' ' const da = typeof code[name] === \"function\";' ' if (da === false) fehlen = fehlen + 1;' ' console.log((da ? \"ok: \" : \"fehlt: \") + name);' '}' 'console.log(fehlen + \" Name(n) von \" + namen.length + \" fehlen im Code\");' > demo-doku/namen.js"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Jeden genannten Namen im Code suchen
docker exec -w /home/node/project/demo-doku agent node namen.jsHier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Auch das beschriebene Verhalten braucht einen Beleg
Die Namen stimmen fast, aber die Dokumentation sagt mehr: buche gebe ein neues Buch zurück, und storniere entferne genau einen Eintrag. Das lässt sich nur durch einen Aufruf prüfen.
Der nächste Run ruft beide Funktionen mit kleinen Listen auf. Vergleichen Sie die Ausgabe mit den beiden Sätzen der Dokumentation.
Die beiden Aufrufe schreiben
docker exec -w /home/node/project agent sh -c "mkdir -p demo-doku && printf '%s\n' 'const k = require(\"./kassenbuch.js\");' 'const buch = [100];' 'const neu = k.buche(buch, 250);' 'console.log(\"buche: altes Buch \" + JSON.stringify(buch) + \", gleiches Objekt: \" + (buch === neu));' 'console.log(\"storniere: \" + JSON.stringify(k.storniere([50, 50, 70], 50)));' > demo-doku/beispiel.js"Hier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Die beiden Behauptungen ausprobieren
docker exec -w /home/node/project/demo-doku agent node beispiel.jsHier angezeigt, nicht ausgeführt. Erstellen Sie ein kostenloses Konto, um „Ausführen“ zu drücken und ihn im Terminal Ihres eigenen Labs einzugeben.
Ein häufiger Fehler
Warnung
Viele denken, eine Dokumentation, die gut klingt und zum Code passt, sei richtig. Zwei Sätze der README waren falsch: Das alte Buch wurde verändert, und alle gleichen Einträge verschwanden. Prüfen Sie Verhalten immer mit einem Aufruf, nicht nur mit dem Lesen.
Beispiel: Behauptungen und ihre Belege
| Behauptung | Beleg im Code | Ergebnis |
|---|---|---|
| buche gibt ein neues Buch zurück | push ändert die Liste selbst | Falsch |
| storniere entfernt einen Eintrag | continue überspringt jeden gleichen | Falsch |
| summe gibt die Summe zurück | Schleife mit s + b | Stimmt |
| tagesabschluss schreibt die Summe | Keine solche Funktion | Fehlt |
Die Zellen, die Lernende ausfüllen, bleiben in dieser Vorschau leer.
Weiter: an einer anderen Datei ausprobieren
Jetzt ist ein guter Moment, diese Ideen an einer anderen Datei auszuprobieren. Der Fehler des Labs bleibt unberührt. Bitten Sie den Assistenten um eine README für eine Kopie von shop.js.
Lesen Sie jede Zeile als Behauptung und suchen Sie den Beleg. Streichen oder korrigieren Sie jede, die keinen hat, und notieren Sie, welche das waren.