Was macht codebase-design?
Entwerfe tiefe Module: viel Verhalten hinter einer kleinen Schnittstelle, platziert an einer sauberen Naht, testbar durch diese Schnittstelle. Verwende diese Sprache und diese Prinzipien überall dort, wo Code entworfen oder umstrukturiert wird. Das Ziel: Hebelwirkung für Aufrufer, Lokalität für Betreuer und Testbarkeit für alle.
Glossar
Verwende diese Begriffe exakt – ersetze sie nicht durch „Komponente“, „Dienst“, „API“ oder „Grenze“. Konsequente Sprache ist der springende Punkt.
Modul — alles mit einer Schnittstelle und einer Implementierung. Bewusst skalierungsneutral: eine Funktion, Klasse, ein Paket oder ein systemübergreifender Abschnitt. Vermeide: Einheit, Komponente, Dienst.
Schnittstelle — alles, was ein Aufrufer wissen muss, um das Modul korrekt zu verwenden: die Typsignatur, aber auch Invarianten, Reihenfolge-Einschränkungen, Fehlermodi, erforderliche Konfiguration und Leistungsmerkmale. Vermeide: API, Signatur (zu eng – beziehen sich nur auf die Typebene).
Implementierung — was sich in einem Modul befindet, sein Codekörper. Unterscheide sie vom Adapter: Ein Ding kann ein kleiner Adapter mit einer großen Implementierung sein (ein Postgres-Repo) oder ein großer Adapter mit einer kleinen Implementierung (ein In-Memory-Fake). Verwende „Adapter“, wenn die Naht das Thema ist; sonst „Implementierung“.
Tiefe — Hebelwirkung an der Schnittstelle: die Menge an Verhalten, die ein Aufrufer (oder Test) pro Einheit Schnittstelle, die er lernen muss, ausüben kann. Ein Modul ist tief, wenn eine große Menge an Verhalten hinter einer kleinen Schnittstelle sitzt, und flach, wenn die Schnittstelle fast so komplex ist wie die Implementierung.
Naht (Michael Feathers) — ein Ort, an dem du Verhalten ändern kannst, ohne an diesem Ort zu bearbeiten; der Ort, an dem die Schnittstelle eines Moduls lebt. Wo die Naht platziert wird, ist eine eigene Designentscheidung, die von dem, was dahinter liegt, zu unterscheiden ist. Vermeide: Grenze (überladen mit dem DDD-Bounded Context).
Adapter — ein konkretes Ding, das eine Schnittstelle an einer Naht erfüllt. Beschreibt die Rolle (welchen Slot es füllt), nicht die Substanz (was darin steckt).
Hebelwirkung — was Aufrufer von der Tiefe bekommen: mehr Fähigkeit pro Einheit Schnittstelle, die sie lernen. Eine Implementierung zahlt sich über N Aufrufstellen und M Tests aus.
Lokalität — was Betreuer von der Tiefe bekommen: Änderungen, Fehler, Wissen und Überprüfung konzentrieren sich an einem Ort, anstatt sich über Aufrufer zu verteilen. Einmal repariert, überall repariert.
Tief vs. flach
Tiefes Modul = kleine Schnittstelle + viel Implementierung:
┌─────────────────────┐
│ Kleine Schnittst. │ ← Wenige Methoden, einfache Parameter
├─────────────────────┤
│ │
│ Tiefe Implement. │ ← Komplexe Logik versteckt
│ │
└─────────────────────┘
Flaches Modul = große Schnittstelle + wenig Implementierung (vermeiden):
┌─────────────────────────────────┐
│ Große Schnittstelle │ ← Viele Methoden, komplexe Parameter
├─────────────────────────────────┤
│ Dünne Implementierung │ ← Leitet nur weiter
└─────────────────────────────────┘
Frage beim Entwerfen einer Schnittstelle:
- Kann ich die Anzahl der Methoden reduzieren?
- Kann ich die Parameter vereinfachen?
- Kann ich mehr Komplexität im Inneren verstecken?
Prinzipien
- Tiefe ist eine Eigenschaft der Schnittstelle, nicht der Implementierung. Ein tiefes Modul kann intern aus kleinen, testbaren, austauschbaren Teilen bestehen – sie sind nur nicht Teil der Schnittstelle. Ein Modul kann interne Nähte (privat in seiner Implementierung, von eigenen Tests verwendet) sowie die externe Naht an seiner Schnittstelle haben.
- Der Löschtest. Stell dir vor, das Modul zu löschen. Wenn die Komplexität verschwindet, war es ein Durchgang. Wenn die Komplexität bei N Aufrufern wieder auftaucht, hat es seinen Wert verdient.
- Die Schnittstelle ist die Testoberfläche. Aufrufer und Tests überschreiten dieselbe Naht. Wenn du an der Schnittstelle vorbei testen möchtest, hat das Modul wahrscheinlich die falsche Form.
- Ein Adapter bedeutet eine hypothetische Naht. Zwei Adapter bedeuten eine echte Naht. Führe keine Naht ein, es sei denn, etwas variiert tatsächlich über sie hinweg.
Entwurf für Testbarkeit
Gute Schnittstellen machen das Testen natürlich:
-
Abhängigkeiten akzeptieren, nicht erzeugen.
// Testbar function processOrder(order, paymentGateway) {} // Schwer zu testen function processOrder(order) { const gateway = new StripeGateway(); } -
Ergebnisse zurückgeben, keine Seiteneffekte erzeugen.
// Testbar function calculateDiscount(cart): Discount {} // Schwer zu testen function applyDiscount(cart): void { cart.total -= discount; } -
Kleine Oberfläche. Weniger Methoden = weniger benötigte Tests. Weniger Parameter = einfachere Testeinrichtung.
Beziehungen
- Ein Modul hat genau eine Schnittstelle (die Oberfläche, die es Aufrufern und Tests präsentiert).
- Tiefe ist eine Eigenschaft eines Moduls, gemessen an seiner Schnittstelle.
- Eine Naht ist der Ort, an dem die Schnittstelle eines Moduls lebt.
- Ein Adapter sitzt an einer Naht und erfüllt die Schnittstelle.
- Tiefe erzeugt Hebelwirkung für Aufrufer und Lokalität für Betreuer.
Abgelehnte Definitionen
- Tiefe als Verhältnis von Implementierungszeilen zu Schnittstellenzeilen (Ousterhout): belohnt das Aufblähen der Implementierung. Wir verwenden stattdessen Tiefe als Hebelwirkung.
- „Schnittstelle“ als das TypeScript-Schlüsselwort
interfaceoder die öffentlichen Methoden einer Klasse: zu eng – die Schnittstelle umfasst hier jede Tatsache, die ein Aufrufer wissen muss. - „Grenze“: überladen mit dem DDD-Bounded Context. Sage Naht oder Schnittstelle.
Tiefer gehen
- Vertiefen eines Clusters unter Berücksichtigung seiner Abhängigkeiten – siehe DEEPENING.md: Abhängigkeitskategorien, Nahtdisziplin und „Ersetzen statt Schichten“-Testen.
- Erkundung alternativer Schnittstellen – siehe DESIGN-IT-TWICE.md: parallele Sub-Agenten starten, um die Schnittstelle auf mehrere radikal unterschiedliche Weisen zu entwerfen und dann hinsichtlich Tiefe, Lokalität und Nahtplatzierung zu vergleichen.