Vereinfachtes Englisch
Übersicht
Regel 1 von Jarretts Regeln: Chat-Ausgaben, generierte Dokumentationen, Code-Kommentare und Commit-Nachrichten verwenden vereinfachtes technisches Englisch. Der Stil basiert auf den Prinzipien von ASD-STE100. Leser finden Fakten schneller. Leser, deren erste Sprache nicht Englisch ist, verstehen mehr.
Diese Fähigkeit ist unsere eigene Zusammenfassung. Sie ist nicht der ASD-STE100-Standard und enthält nicht dessen Wörterbuch.
Wann verwenden
- Sie schreiben oder bearbeiten eine Spezifikation, einen Plan, einen ADR, eine README, einen Vokabulareintrag oder ein anderes Dokument.
- Sie schreiben einen Code-Kommentar oder eine Commit-Nachricht.
- Sie überprüfen Text auf Regel 1 hin.
Wenden Sie sie nicht auf Code-Identifikatoren, zitierte Ausgaben (Fehler, Logs, Befehlsausgaben), Fähigkeitsdateien oder vom Benutzer geschriebenen Text an.
Prozess
Schreiben Sie den Text. Prüfen Sie ihn dann gegen jede Regel.
| # | Regel | Nicht so | So |
|---|---|---|---|
| 1 | Ein Thema pro Satz. | Der Hook liest die Datei und, wenn sie fehlt, gibt er eine Warnung aus, die der Benutzer sieht. | Der Hook liest die Datei. Wenn die Datei fehlt, gibt der Hook eine Warnung aus. Der Benutzer sieht die Warnung. |
| 2 | Anweisungen: 20 Wörter oder weniger. Beschreibungen: 25 Wörter oder weniger. | Stellen Sie sicher, dass Sie, bevor Sie den Branch pushen, die vollständige Testsuite ausgeführt und die Ausgabe überprüft haben. | Führen Sie ./scripts/test.sh aus. Pushen Sie dann den Branch. |
| 3 | Verwenden Sie die aktive Stimme. | Die Regeln werden vom Hook geladen. | Der Hook lädt die Regeln. |
| 4 | Anweisungen verwenden den Imperativ. | Der Test sollte vor dem Commit ausgeführt werden. | Führen Sie den Test vor dem Commit aus. |
| 5 | Ein Wort hat eine Bedeutung. Verwenden Sie die Begriffe in .claude-work/docs/VOCABULARY.md. | Warnen, dann später "flag", "alert" oder "notify" für die gleiche Aktion. | Warnen, jedes Mal. |
| 6 | Verwenden Sie einfache Zeitformen: Präsens, Präteritum, Futur. | Der Hook hätte die Eingabe überprüft. | Der Hook überprüft die Eingabe. |
| 7 | Verwenden Sie ein einzelnes Verb, kein Phrasal Verb oder Idiom. | Starten Sie den Build. Finden Sie die Ursache heraus. | Starten Sie den Build. Finden Sie die Ursache. |
| 8 | Behalten Sie "the" und "a". | Run script, check output. | Run the script. Check the output. |
| 9 | Ein Schritt pro Anweisung. | 1. Öffnen Sie die Datei und ändern Sie die Version. | 1. Öffnen Sie die Datei. 2. Ändern Sie die Version. |
| 10 | Absätze: 6 Sätze oder weniger. | Ein Block mit zehn Sätzen. | Zwei kurze Absätze oder eine Liste. |
Weitere Regeln:
- Schreiben Sie eine Warnung oder Vorsicht vor dem Schritt, auf den sie sich bezieht. Beginnen Sie mit der Gefahr: "Warning: this deletes the branch."
- Verwenden Sie Zahlen, keine Wörter, für Werte: "72 characters", nicht "seventy-two characters".
- Verwenden Sie eine Liste oder eine Tabelle, wenn Sie drei oder mehr Elemente angeben.
- Verwenden Sie keine Synonyme, um den Text abwechslungsreich zu gestalten. Wiederholen Sie denselben Begriff.
- Verwenden Sie nicht "it" oder "this", wenn das Nomen nicht klar ist. Nennen Sie das Nomen erneut.
- Wenn ein Begriff nicht im Vokabular ist und die Bedeutung nicht klar ist, fragen Sie den Benutzer. Fügen Sie dann den Begriff zum Vokabular hinzu.
Häufige Rationalisierungen
| Rationalisierung | Realität |
|---|---|
| "Kurze Sätze klingen roboterhaft." | Kurze Sätze sind schnell zu lesen und schwer falsch zu verstehen. Die Geschwindigkeit des Lesers ist wichtiger als der Stil. |
| "Ein Synonym macht den Text weniger eintönig." | Ein Synonym lässt den Leser fragen, ob es eine andere Sache ist. |
| "Dieser Kommentar ist zu klein für die Regeln." | Kommentare und Commit-Nachrichten sind im Geltungsbereich. Kleiner Text ist leicht zu korrigieren. |
| "Das Passiv ist formeller." | Das Passiv verbirgt, wer die Handlung ausführt. Nennen Sie den Akteur. |
Warnsignale
- Sätze mit "and", "which" oder "so that", die zwei Themen verbinden.
- "Should", "could" oder "might" in einer Anweisung.
- Dasselbe Ding hat zwei Namen in einem Dokument.
- Ein Schritt mit zwei Aktionen.
- Eine Warnung nach dem Schritt, auf den sie sich bezieht.
Verifikation
- Jeder Satz hat ein Thema.
- Keine Anweisung ist länger als 20 Wörter. Keine Beschreibung ist länger als 25 Wörter.
- Alle Anweisungen verwenden den Imperativ und die aktive Stimme.
- Alle Begriffe stimmen mit dem Vokabular überein.
- Jeder Listenschritt hat eine Anweisung.
- Kein Absatz ist länger als 6 Sätze.