Entwurf · Issue 75f9042

Ein Modul erklärt sich selbst

Entwurf zu Issue 75f9042, zu docs/plans/75f9042-every-module-explains-itself.md.

Was ein Leser versteht, entscheidet sich daran, was im Moment des Lesens vor ihm liegt — bei einem Menschen wie bei einem Modell, das eine Datei in seinen Kontext holt. Der Modul-Header ist die Regel, die dort steht, wo ihre Leser sind: das Warum vor dem Code, in derselben Datei, bei jedem Öffnen. Ein zentrales Dokument sagt dasselbe und ist in dem Moment nicht da.

01Die Regel, und wer sie hält

Jedes Modul unter lib/ beginnt mit einem Docblock vor der ersten Deklaration; Importe dürfen darüberstehen. board.ts, chain.ts und issue-spec.ts haben das Muster gesetzt — gehalten hat es bis zu dieser Karte nichts: sechs Module trugen gar keinen Header, und ein Muster, das nur aus Nachahmung besteht, verfällt Modul für Modul.

  • Form wird geprüft, Inhalt wird gelesen. Der Test verlangt, DASS ein Header dasteht — ob er ein Essay ist oder ein Alibi, ist eine Review-Frage. Dieselbe Linie zieht die Kette: das Gate prüft, dass ein Plan existiert, ob er taugt, liest ein Mensch.
  • Was diese Seite nicht sehen kann: den Quelltext. Im laufenden Container liegt kein lib/ — die Prüfung gehört deshalb in die Suite, und dieses Kapitel nennt sie: lib/module-headers.test.ts, rot für jedes Modul, das mit Code statt einem Docblock beginnt.
  • Nur lib/: die Regel beginnt, wo das Muster schon lebt. Komponenten und Skripte erklären sich anders — eine Regel, die überall gilt, bevor sie irgendwo gehalten wird, ist keine.

hält der Draft-Lookup der Issue-Seite findet dieses Kapitel