17. Sept. 2025·8 Min
Wie Framework‑Konventionen den Bedarf an Dokumentation reduzieren
Framework‑Konventionen machen Code verständlicher ohne lange Docs. Erfahre, was Konventionen abdecken, wo sie versagen und wie du nur die Ausnahmen dokumentierst.
Framework‑Konventionen machen Code verständlicher ohne lange Docs. Erfahre, was Konventionen abdecken, wo sie versagen und wie du nur die Ausnahmen dokumentierst.
Framework‑Konventionen sind die „Standardweisen“, wie ein Framework stillschweigend empfiehlt — oder sogar erwartet. Anstatt dass jedes Team seine eigene Ordnerstruktur, Benennungsregeln oder Anfrage/Antwort‑Abläufe erfindet, liefert das Framework ein gemeinsames Muster. Wenn du ihm folgst, können andere Entwickelnde vorhersagen, wo Dinge liegen und wie sie sich verhalten, ohne eine lange Erklärung lesen zu müssen.
Die meisten Dokumente entstehen nicht, weil Menschen gerne Docs schreiben. Sie existieren, um einige wiederkehrende Probleme zu lösen:
Konventionen lösen besonders die ersten beiden Punkte gut. Wenn „wo packen wir X hin“ und „wie nennen wir Y“ bereits vom Framework entschieden sind, gibt es weniger zu erklären und weniger zu diskutieren.
„Konventionen ersetzen Dokumentation“ heißt nicht, dass ein Projekt völlig dokumentationsfrei wird. Es bedeutet, dass ein großer Teil der grundlegenden Anleitung von Fließtext in vorhersehbare Struktur wandert. Statt ein Wiki lesen zu müssen, um zu lernen, wo Controller liegen, schließt du daraus, weil das Framework Controller an einem bestimmten Ort erwartet (und Tools, Generatoren und Beispiele verstärken das).
Das Ergebnis ist weniger Dokumentation über das Offensichtliche und mehr Fokus auf das, was wirklich projektspezifisch dokumentiert werden muss: Geschäftsregeln, ungewöhnliche Architekturentscheidungen und beabsichtigte Ausnahmen.
Dieser Artikel richtet sich an Entwickler:innen, Tech‑Leads und produktorientierte Teams, die klarere Codebasen und schnelleres Onboarding ohne ein ausuferndes Dokumentationsportal wollen.
Du lernst, wie Framework‑Konventionen "implizite Dokumentation" erzeugen, welche Dinge Konventionen typischerweise standardisieren, wo Konventionen aufhören zu helfen und was trotzdem explizit dokumentiert werden sollte — damit die Klarheit steigt, während die Menge der Docs sinkt.
„Convention over configuration“ bedeutet, dass ein Framework sinnvolle Entscheidungen für dich trifft — vorausgesetzt, du hältst dich an die vereinbarten Regeln. Anstatt Seiten voller Setup‑Anweisungen zu schreiben (und zu lesen), verlassen sich Teams auf geteilte Defaults, die jede:r wiedererkennt.
Stell dir vor, du fährst in einem Land, in dem alle zustimmen, rechts zu fahren, bei Rot anzuhalten und standardisierte Schilder zu beachten.
Du könntest ein detailliertes Handbuch für jede Kreuzung schreiben („Wenn du ein rotes Achteck siehst, halte an; wenn die Ampel grün ist, fahr…“), aber du brauchst das nicht — weil die Konvention bereits bekannt und konsistent angewendet wird.
Framework‑Konventionen funktionieren genauso: sie verwandeln „wie wir hier Dinge tun“ in vorhersehbares Verhalten.
Wenn ein Framework Defaults hat, musst du nicht jede kleine Entscheidung dokumentieren. Das Framework (und dein Team) kann Muster annehmen wie:
User‑Modell mappt auf users‑Daten)Diese gemeinsame Basis schrumpft die Dokumentation von „hier sind alle Schritte, um X einzurichten“ zu „wir folgen den Framework‑Defaults, außer wenn anders angegeben.“ Sie reduziert auch die mentale Last beim Onboarding: neue Entwickler:innen können öfter richtig raten, weil der Code dem entspricht, was sie in anderen Projekten gesehen haben.
Konventionen sind nicht umsonst. Der Nachteil ist, dass du manchmal auf ungewöhnliche Ordnerstrukturen, individuelle Benennungen oder stark maßgeschneiderte Workflows verzichtest.
Der Vorteil ist Konsistenz: weniger Debatten, weniger Überraschungen, weniger „tribal knowledge“, an das nur alteingesessene Mitarbeitende sich erinnern. Teams bewegen sich schneller, weil sie weniger Zeit mit Erklärungen und mehr Zeit mit Bauen verbringen.
Eine Konvention spart nur dann Dokumentation, wenn Leute sie bereits kennen — oder sie einmal lernen können und überall wiederverwenden. Deshalb sind populäre Frameworks so mächtig: die Konventionen werden breit gelehrt, vielfach genutzt und in vielen Codebasen wiederholt. Wenn dein Projekt eng an diesen geteilten Defaults bleibt, wird dein Code von Haus aus verständlich, mit deutlich weniger schriftlichen Erklärungen.
Framework‑Konventionen sind gemeinsame Abkürzungen. Sie standardisieren die Fragen, die jedes neue Teammitglied am ersten Tag stellt: „Wohin gehört das?“ und „Wie nennen wir das?“ Wenn diese Antworten vorhersehbar sind, kannst du Seiten an Docs durch ein paar konsistente Defaults ersetzen.
Die meisten Frameworks treiben eine erkennbare Projektstruktur voran: ein Platz für UI, ein Platz für Routen, ein Platz für Datenzugriff, ein Platz für Tests. Diese Konsistenz ist wichtig, weil Menschen nicht mehr erst eine Anleitung lesen müssen, um „den Teil, der eine Seite rendert“ von „dem Teil, der mit der Datenbank spricht“ zu unterscheiden.
Die besten Konventionen lassen häufige Aufgaben wie Muskelgedächtnis erscheinen: neue Seite hinzufügen → du weißt schon, in welchen Ordner sie gehört.
Benennungsregeln reduzieren die Notwendigkeit für Erklärungen wie „Unsere Controller sind in X und müssen in Y verdrahtet werden.“ Stattdessen implizieren Namen Rollen.
Gängige Beispiele:
Viele Webframeworks mappen Dateien auf Routen (oder machen Routing einfach zu erschließen). Wenn du die URL aus dem Dateinamen erraten kannst — oder umgekehrt — brauchst du für jede Funktion kein eigenes Routing‑Handbuch.
Die Konvention setzt auch Erwartungen an dynamische Routen, verschachtelte Routen und 404‑Handhabung, sodass „wie füge ich einen neuen Endpoint hinzu?“ eine standardisierte Antwort hat.
Konventionen definieren oft, wo „Daten‑Code“ lebt: Modelle, Repositories, Services, Migrationen, Schema‑Dateien. Selbst wenn die App klein ist, verhindert ein vereinbarter Ort für Datenzugriff ad‑hoc‑Datenbankaufrufe, die überall in der UI verstreut sind.
Standardbefehle (run, test, build, lint, format) beseitigen Unklarheit. Eine neue Entwicklerin oder ein neuer Entwickler sollte nicht erst ein Wiki lesen müssen, um das Projekt zu starten — npm test (oder das entsprechende Äquivalent) sollte die naheliegende Wahl sein.
Wenn diese fünf Bereiche konsistent sind, beantwortet die Codebasis die meisten „wie machen wir das hier?“‑Fragen selbst.
Ein „wie alles funktioniert“‑Wiki versucht, das gesamte System in Prosa zu beschreiben. Es ist oft am Anfang nützlich, driftet dann aber aus dem Tritt, wenn Ordner verschoben, Namen geändert und neue Features hinzugefügt werden. Konventionen kehren diese Idee um: statt eine lange Erklärung zu lesen, liest du die Struktur.
Wenn ein Framework (und dein Team) sich darauf einigt, wo Dinge leben, wird das Repository wie ein Straßenraster navigierbar.
Wenn du weißt, dass UI‑Komponenten in components/ gehören, Seiten‑Views in pages/ und API‑Handler in api/ liegen, fragst du nicht mehr „wo ist X?“, denn die erste Vermutung ist meist richtig. Selbst wenn nicht, ist die Suche eingeschränkt: es ist nicht irgendwo — es ist in einer kleinen Anzahl erwarteter Orte.
Konventionen lassen Dateinamen und Symbole Bedeutung tragen. Eine neue Person kann Verhalten aus Lage und Benennung ableiten:
user.controller behandelt wahrscheinlich Request‑LogikUserService enthält vermutlich Geschäftsregelnmigrations/ enthält wahrscheinlich geordnete, einmal auszuführende DatenbankänderungenDiese Schlüsse reduzieren „erklär mir die Architektur“‑Fragen auf kleinere, beantwortbare Fragen („Darf dieser Service direkt die DB aufrufen?“), die sich leichter dokumentieren lassen.
Der schnellste Weg, die Karte zu verstärken, ist Scaffolding. Starter‑Templates und Generatoren erzeugen neue Features standardmäßig in der „richtigen“ Form — Ordner, Dateinamen, Boilerplate‑Verdrahtung und oft Tests.
Das ist wichtig, weil Konventionen nur helfen, wenn sie konsistent angewandt werden. Ein Template ist eine Leitplanke: es schiebt jede neue Route, Komponente oder Modul in die erwartete Struktur, sodass die Codebasis lesbar bleibt, ohne dass zusätzliche Wiki‑Seiten nötig sind.
Wenn du interne Scaffolds pflegst, verlinke sie von einer kurzen Onboarding‑Seite (zum Beispiel /docs/getting-started) und lass den Ordnerbaum den Rest erledigen.
Framework‑Konventionen wirken oft wie leise, eingebaute Anweisungen. Anstatt eine Seite zu schreiben, die erklärt „wo Dinge hingehören“ oder „wie man das verdrahtet“, trifft das Framework schon die Entscheidung — und dein Team lernt, die Struktur zu lesen.
Rails ist berühmt für Konvention vor Konfiguration. Ein einfaches Beispiel: wenn du einen Controller namens OrdersController erstellst, geht Rails davon aus, dass es einen passenden View‑Ordner in app/views/orders/ gibt.
Diese einzelne Konvention kann einen Teil der Dokumentation ersetzen, die sonst erklären würde:
Ergebnis: neue Teammitglieder können eine Seite hinzufügen, indem sie dem Ordner‑Pattern folgen, ohne zu fragen „wo gehört diese Datei hin?“
Django fördert eine konsistente „App“‑Struktur. Wenn jemand eine Django‑App sieht, erwartet er/sie models.py für Datenformen, views.py für Request‑Handling und templates/ für HTML.
Man könnte eine lange Anleitung zur Projektanatomie schreiben, aber Djangos Defaults lehren das bereits. Wenn ein Teammitglied das Aussehen einer Seite ändern will, schaut es in templates/. Muss gespeicherte Daten angepasst werden, fängt es in models.py an.
Ergebnis: schnellere Fehlerbehebungen, weniger Sucherei, weniger „welche Datei kontrolliert das?“‑Nachrichten.
Next.js reduziert die Dokumentation, indem Routing eine direkte Spiegelung deiner Ordnerstruktur wird. Erstelle eine Datei in app/about/page.tsx (oder pages/about.tsx in älteren Setups) und du bekommst automatisch eine /about‑Seite.
Das erspart Docs, die erklären:
Ergebnis: Onboarding ist einfacher — Leute entdecken die Form der Website durch Verzeichnisdurchsicht.
Rails, Django und Next.js sehen unterschiedlich aus, aber das Prinzip ist identisch: geteilte Defaults verwandeln Projektstruktur in Anweisungen. Wenn alle denselben Konventionen vertrauen, beantwortet die Codebasis viele „wie machen wir das hier?“‑Fragen von selbst — ohne ein weiteres zu wartendes Dokument.
Framework‑Konventionen wirken „unsichtbar“, wenn sie funktionieren. Du kannst erraten, wo Dateien liegen, wie Dinge heißen und wie eine Anfrage durch die App fließt. Verwirrung kehrt zurück, wenn eine Codebasis von diesen geteilten Defaults abweicht.
Einige Muster treten früh auf:
UserService, ein anderer UsersManager, ein dritter user_serviceDas ist nicht automatisch falsch — aber es bedeutet, dass neue Teammitglieder sich nicht mehr auf die „Karte“ des Frameworks verlassen können.
Die meisten Zusammenbrüche von Konventionen beginnen mit einer sinnvollen lokalen Optimierung: „Dieses Feature ist besonders, also legen wir es hier hin“ oder „Diese Benennung liest sich besser.“ Das Problem ist, dass Ausnahmen ansteckend sind. Sobald die erste Ausnahme deployed ist, nutzt die nächste Entwicklerin oder der nächste Entwickler sie als Präzedenzfall:
An diesem Punkt ist die Konvention keine Konvention mehr — sie wird zu Tribal Knowledge.
Wenn Konventionen verschwimmen, verlangsamt sich das Onboarding, weil Menschen nicht mehr vorhersagen können, wo sie suchen müssen. Alltägliche Aufgaben dauern länger („Welcher dieser Ordner ist der richtige?“), Fehler häufen sich (falsches Modul verdrahten, falsches Benennungsschema verwenden, Logik duplizieren). Teams kompensieren mit mehr Synchronisationsmeetings, ausführlicheren PR‑Erklärungen und kurzen Docs, die veralten.
Passe nur an, wenn du einen klaren Grund hast — und hinterlasse eine schriftliche Notiz.
Diese Notiz kann leicht sein: ein kurzer Kommentar in der Nähe der ungewöhnlichen Struktur oder ein knapper Eintrag auf einer /docs/decisions‑Seite, der erklärt, was sich geändert hat, warum es sich lohnt und wie zukünftig vorzugehen ist.
Framework‑Konventionen können Seiten an Erklärungen ersetzen, aber sie nehmen nicht die Verantwortung ab. Was weiterhin dokumentiert werden muss, sind die Bereiche, in denen dein Projekt bewusst vom erwarteten Verhalten abweicht.
Erkläre nicht noch einmal das Standardverhalten des Frameworks. Halte stattdessen Entscheidungen fest, die den Alltag beeinflussen:
Beispiel: „Wir verwenden Feature‑Ordner unter /src/features statt Schichtenordner (/src/components, /src/services), weil Ownership zu Teams passt und Cross‑Team‑Kopplung reduziert.“ Dieser Satz verhindert Wochen langsamen Abdriftens.
Wenn eine Ausnahme lokal wichtig ist, setze die Notiz lokal. Ein kleines README.md im Ordner oder ein kurzer Header‑Kommentar an der Datei schlägt oft ein zentrales Wiki, das niemand liest.
Gute Kandidaten:
Halte diese Hinweise kurz und handlungsorientiert: was ist anders, warum ist es anders und was ist als Nächstes zu tun.
Habe eine leichte Seite (oft in /docs/project-rules.md oder im root‑README), die nur 5–10 Schlüsselentscheidungen listet, über die Leute stolpern werden:
Das ist kein vollständiges Handbuch — nur ein Satz von Leitplanken.
Auch mit Konventionen stockt das Onboarding, wenn Leute die App nicht starten können. Füge eine kurze „How to run/test“‑Sektion hinzu, die zu den Standardbefehlen und deiner tatsächlichen Einrichtung passt.
Wenn der konventionelle Befehl npm test ist, dein Projekt aber npm run test:unit benötigt, dokumentiere das explizit.
Dokumentation bleibt korrekt, wenn sie als Teil der Änderung behandelt wird. Frage in Reviews: „Hat das eine neue Ausnahme eingeführt?“ Wenn ja, fordere die passende Notiz (lokales README, Project Rules oder root Quickstart) in demselben Pull Request an.
Wenn Konventionen die „geteilten Defaults“ deines Repos sind, macht Automatisierung sie real. Statt jede Entwicklerin und jeden Entwickler zu bitten, Regeln aus einem Wiki zu merken, mache die Regeln ausführbar — so erzwingt das Projekt sich selbst.
Eine gute Einrichtung fängt Drift früh und leise ab:
*.spec.ts, konsistente describe/it‑Formulierungen oder erforderliche Assertions, sodass Tests konsistent lesbar sindDiese Checks ersetzen Abschnitte mit „bitte merkt euch…“ durch ein einfaches Ergebnis: der Code entspricht entweder der Konvention oder er tut es nicht.
Automatisierung ist stark, weil sie früh scheitert:
Die besten Regelsets sind klein und unspektakulär. Starte mit den Defaults des Frameworks und füge nur hinzu, was Klarheit schützt (Benennung, Struktur, Grenzen). Jede zusätzliche Regel ist etwas, das Menschen verstehen müssen — behandle neue Checks wie Code: füge sie hinzu, wenn sie ein wiederkehrendes Problem lösen, und entferne sie, wenn sie nicht mehr helfen.
Wenn eine Codebasis Framework‑Konventionen folgt, können Tests mehr als „beweisen, dass es funktioniert“: sie können erklären, was das System tun soll, in klarer Sprache, direkt neben der Implementierung.
Eine nützliche Regel: ein Test sollte ein Verhalten end‑to‑end beschreiben. Wenn jemand nur den Testnamen überfliegen kann und das Versprechen des Systems versteht, hast du die Notwendigkeit separater Dokumentation reduziert.
Gute Tests folgen oft einem einfachen Rhythmus:
Noch besser sind Namen, die die Nutzerintention spiegeln:
signing_in_with_valid_credentials_redirects_to_dashboardcheckout_fails_when_shipping_address_is_missingDiese Namen sind Dokumentation, die man nicht vergisst zu aktualisieren — weil fehlschlagende Tests die Diskussion erzwingen.
Acceptance‑ oder Feature‑Tests dokumentieren besonders gut wie sich das Produkt aus Nutzersicht verhält.
Beispielverhalten, das Acceptance‑Tests beschreiben können:
Diese Tests beantworten die Frage „Was passiert, wenn ich X tue?“ — oft das Erste, was neue Teammitglieder wissen wollen.
Unit‑Tests sind ideal, wenn du „kleine, aber wichtige“ Regeln dokumentieren willst:
Sie sind besonders wertvoll, wenn die Regel nicht aus den Framework‑Konventionen ersichtlich ist.
Beispieldaten können ebenfalls lebende Dokumentation sein. Eine kleine, sinnvoll benannte Fixture (z. B. user_with_expired_subscription) lehrt die Domäne oft schneller als ein Absatz im Wiki.
Der Schlüssel ist Zurückhaltung: halte Fixtures minimal, lesbar und an eine Idee gebunden, damit sie vertrauenswürdige Beispiele bleiben statt ein zweites System, das gepflegt werden muss.
Starter‑Templates (und die dahinterstehenden Generatoren) sind der schnellste Weg, „wie wir hier arbeiten“ in etwas zu verwandeln, dem Menschen tatsächlich folgen. Anstatt jede Teammitarbeiterin und jeden Teammitarbeiter zu bitten, sich die richtigen Ordner, Skripte und Tools zu merken, backst du diese Entscheidungen in ein Repo, das korrekt startet.
Alle drei reduzieren „Dokumentationsschuld“, weil die Konvention im Startpunkt kodiert ist und nicht in einem driftenden Wiki.
In der Praxis ist das auch der Punkt, an dem Tools wie Koder.ai helfen können: wenn du eine neue React‑App, ein Go‑Backend, ein PostgreSQL‑Schema oder einen Flutter‑Client aus einem Chat‑gesteuerten Workflow generierst, kannst du Teams auf einem einzigen "goldenen Pfad" halten, indem du die Standardausgabe an deine Konventionen anpasst (und dann den Quellcode ins Repo übernimmst).
Die meiste Verwirrung beim Onboarding betrifft nicht Business‑Logik, sondern wo Dinge liegen und wie man sie startet. Ein gutes Template macht gemeinsame Aufgaben in allen Repos identisch: gleiche Skripte, gleiche Ordnernamen, gleiche Prüf‑Befehle, gleiche PR‑Erwartungen.
Wenn du nichts anderes tust, stimme ab auf:
/src, /test, /docs nur für Ausnahmen)Halte sie so klein, dass Teams sie nicht überspringen:
install + dev)test, lint und format‑SkripteDas größte Risiko ist, ein altes Template zu kopieren „weil es letztes Jahr funktioniert hat“. Veraltete Dependencies, Legacy‑Skripte oder aufgegebene Muster verbreiten sich schnell, wenn sie im Starter stecken.
Behandle Templates wie Produkte: versioniere sie, überprüfe sie in regelmäßigen Abständen und aktualisiere sie, wenn sich deine Konventionen ändern. (Wenn deine Plattform Snapshots und Rollbacks unterstützt — Koder.ai tut das — nutze das, um Starter sicher zu iterieren, ohne die Basis zu brechen.)
Dokumentation zu reduzieren heißt nicht, Menschen im Dunkeln zu lassen. Es heißt, den „Happy Path“ so konsistent zu machen, dass die meisten Fragen sich von selbst beantworten, und nur die wirklich ungewöhnlichen Teile aufzuschreiben.
Suche nach Stellen, an denen Leute wiederholt dieselben Fragen in Slack, PR‑Kommentaren, Standups oder Onboarding‑Sessions stellen. Ein paar Stichfragen:
Wenn du dieselbe Frage zwei Mal hörst, brauchst du wahrscheinlich weniger Prosa — du brauchst eine Konvention.
Für jede wiederkehrende Frage entscheide:
Eine nützliche Regel: wenn eine Abweichung keine echte Zeitersparnis bringt oder kein Risiko verhindert, ist sie es vermutlich nicht wert.
Halte eine einzige, kurze Seite (z. B. /docs/conventions) bereit, die auflistet:
Beschränke dich auf das, was jemand in der ersten Woche braucht. Wenn die Seite wächst, ist das oft ein Zeichen, dass du die Codebasis vereinfachen solltest.
Apps entwickeln sich. Plane eine leichte Quartalsüberprüfung:
Bevorzuge Framework‑Defaults, wann immer möglich, und dokumentiere nur das, was anders ist — klar, kurz und an einem Ort.
Framework‑Konventionen sind die Standardmuster, denen ein Framework erwartet, dass man folgt — Ordnerstruktur, Benennung, Routing, Datenzugriff und gängige Befehle. Wenn man sich an sie hält, können andere Entwicklerinnen und Entwickler daraus schließen, wo Dateien liegen und wie sie funktionieren, ohne projektspezifische Docs zu lesen.
Weil es schwer ist, Fließtext aktuell zu halten, entsteht viel Dokumentation, um drei Probleme zu lösen:
Konventionen lösen vor allem die ersten beiden Punkte, weil die Struktur vorhersehbar wird.
Nein. Konventionen reduzieren die Dokumentation über Offensichtliches (wo Dateien liegen, wie Routen verbunden werden), aber du musst weiterhin projekt‑spezifisches dokumentieren: Geschäftsregeln, absichtliche Abweichungen und zentrale Entscheidungen. Denke: weniger Dokumentation, dafür höherer Wert der verbleibenden Dokumente.
Sie standardisieren die wiederkehrenden "Tag‑eins"‑Fragen:
Wenn Code einem bekannten Muster folgt, werden Verzeichnisbaum und Dateinamen zu Wegweisern. Eine neue Person navigiert nach Erwartung (z. B. „Templates liegen in templates/“, „Migrationen in migrations/“) statt eine lange Architekturseite zu lesen, die veraltet sein könnte.
Sie kodieren die Konventionen in Standard‑Ausgaben, sodass Leute sich nicht auf ihr Gedächtnis verlassen müssen. Gute Scaffolds erzeugen:
Das verhindert Drift und hält die „Karte“ über Features hinweg konsistent.
Du merkst es, wenn Entwicklerinnen und Entwickler nicht mehr vorhersagen können, wo etwas liegt oder wie es heißt. Typische Signale:
UserService vs. UsersManager vs. user_service)Dann kompensiert das Team mit Slack‑Erklärungen, langen PR‑Beschreibungen und veralteten „Quick Docs“.
Nur bei klarem Nutzen anpassen — und hinterlasse eine leichte Erklärung:
README.md im ungewöhnlichen Ordner/docs/decisions oder ÄhnlichemHalte fest: was geändert wurde, warum und wie weiter vorzugehen ist.
Beginne mit einer kleinen, praktischen Basis:
Halte es schlank und fordere in Code‑Reviews eine Aktualisierung, wenn eine Änderung eine neue Ausnahme einführt.
Automatisiere Konventionen, damit das Projekt sich selbst durchsetzt:
Wenn Prüfungen lokal oder in PRs fehlschlagen, lernen Entwicklerinnen und Entwickler die Regeln sofort — und Reviewer müssen weniger Stil‑Polizei spielen.
Wenn diese Antworten vorhersagbar sind, erklärt sich das Repo weitgehend von selbst.