Frameworkconventies maken apps makkelijker te begrijpen zonder uitgebreide docs. Lees welke gebieden conventies dekken, waar ze falen en hoe je alleen uitzonderingen documenteert.
Frameworkconventies zijn de “standaardmanieren om dingen te doen” die een framework stilletjes aanmoedigt—or zelfs verwacht. In plaats van dat elk team zijn eigen mapindeling, naamgevingsschema of request/response-flow uitvindt, biedt het framework een gedeeld patroon. Volg je dat patroon, dan kunnen andere ontwikkelaars voorspellen waar iets staat en hoe het zich gedraagt zonder een lange toelichting.
De meeste documentatie ontstaat niet omdat mensen dol zijn op het schrijven ervan. Het bestaat om een paar terugkerende problemen op te lossen:
Conventies pakken vooral de eerste twee goed aan. Als “waar zet je X” en “hoe noem je Y” al door het framework zijn vastgesteld, is er minder uit te leggen en minder te discussiëren.
“Conventies vervangen documentatie” betekent niet dat een project documentatievrij wordt. Het betekent dat een groot deel van de basisrichtlijnen van proza naar voorspelbare structuur verhuist. In plaats van een wiki-pagina te lezen om te leren waar controllers horen, leid je dat af omdat het framework controllers op een bepaalde plek verwacht (en tools, generators en voorbeelden dat versterken).
Het resultaat is minder documentatie over het voor de hand liggende, en meer focus op het documenteren van wat echt projectspecifiek is: businessregels, ongebruikelijke architectuukeuzes en opzettelijke uitzonderingen.
Dit artikel is voor ontwikkelaars, tech leads en productgerichte teams die duidelijke codebases en snellere onboarding willen zonder een enorme documentatiesite te onderhouden.
Je leert hoe frameworkconventies “impliciete documentatie” creëren, welke dingen conventies meestal standaardiseren, waar conventies ophouden te helpen en wat nog expliciet gedocumenteerd moet worden—zodat duidelijkheid toeneemt terwijl docs afnemen.
“Convention over configuration” betekent dat een framework verstandige keuzes voor je maakt—mits je de afgesproken regels volgt. In plaats van pagina's met setupinstructies te schrijven (en te lezen), vertrouwen teams op gedeelde defaults die iedereen herkent.
Vergelijk het met autorijden in een land waar iedereen het ermee eens is om rechts te rijden, rood licht te stoppen en standaardborden te volgen.
Je zou een gedetailleerde handleiding voor elk kruispunt kunnen schrijven (“Als je een rood achthoekig bord ziet, stop; als het licht groen is, ga…”), maar dat is niet nodig—want de conventie is al bekend en consistent toegepast.
Frameworkconventies werken op dezelfde manier: ze veranderen “hoe we hier dingen doen” in voorspelbaar gedrag.
Als een framework defaults heeft, hoef je niet elke kleine beslissing te documenteren. Het framework (en je team) kan patronen aannemen zoals:
User model map naar users data)Die gedeelde basis verkleint documentatie van “hier is elke stap om X op te zetten” naar “we volgen de frameworkdefaults, behalve waar anders aangegeven.” Het vermindert ook de mentale last tijdens onboarding: nieuwe ontwikkelaars raden vaker correct, omdat de code overeenkomt met wat ze in andere projecten hebben gezien.
Conventies zijn niet gratis. Het nadeel is dat je soms afziet van ongebruikelijke mapstructuren, aangepaste naamgeving of zeer op maat gemaakte workflows.
Het voordeel is consistentie: minder discussies, minder verrassingen, minder “tribal knowledge”-regels die alleen door veterans worden onthouden. Teams werken sneller omdat ze minder tijd besteden aan uitleggen en meer tijd aan bouwen.
Een conventie bespaart alleen documentatie als mensen hem al kennen—of hem één keer kunnen leren en overal hergebruiken.
Daarom zijn populaire frameworks krachtig: de conventies worden breed onderwezen, veel gebruikt en herhaald in veel codebases. Als je project dicht bij die gedeelde defaults blijft, wordt je codebase standaard begrijpelijk met veel minder geschreven uitleg.
Frameworkconventies zijn gedeelde snelkoppelingen. Ze standaardiseren de vragen die iedere nieuwe collega op dag één stelt: “Waar hoort dit?” en “Hoe noemen we dit?” Als die antwoorden voorspelbaar zijn, kun je pagina's docs vervangen door een paar consistente defaults.
De meeste frameworks stimuleren een herkenbare projectstructuur: een plek voor UI, een plek voor routes, een plek voor data-toegang, een plek voor tests. Die consistentie is belangrijk omdat mensen geen gids hoeven te lezen om “het deel dat een pagina rendert” te vinden versus “het deel dat met de database praat.”
De beste conventies zorgen dat veelvoorkomende taken aanvoelen als spierherinnering: voeg een nieuw scherm toe en je weet al in welke map het hoort.
Naamgevingsregels verminderen de noodzaak om uit te leggen “Onze controllers staan in X en moeten in Y worden aangesloten.” In plaats daarvan impliceren namen rollen.
Veelvoorkomende voorbeelden:
Veel webframeworks koppelen bestanden aan routes (of maken routes makkelijk af te leiden). Als je de URL uit de bestandsnaam kunt raden—of omgekeerd—heb je geen aparte routing-handleiding voor elke feature nodig.
De conventie zet ook verwachtingen rond dynamische routes, geneste routes en 404-afhandeling, zodat “hoe voegen we een nieuwe endpoint toe?” een standaardantwoord heeft.
Conventies definiëren vaak waar “data-code” hoort: models, repositories, services, migrations, schema-bestanden. Zelfs als je app klein is, voorkomt een afgesproken thuis voor data-toegang dat ad-hoc databasecalls door UI-code worden verspreid.
Standaardcommando's (run, test, build, lint, format) halen ambiguïteit weg. Een nieuwe ontwikkelaar hoeft geen wiki-pagina te lezen om te achterhalen hoe het project te starten—npm test (of het equivalent) moet de voor de hand liggende stap zijn.
Als deze vijf gebieden consistent zijn, beantwoordt de codebase zelf de meeste “hoe doen we hier dingen?”-vragen.
Een “hoe alles werkt”-wiki probeert het hele systeem in proza te beschrijven. Het begint vaak nuttig, maar raakt verouderd als mappen verplaatsen, namen veranderen en nieuwe features verschijnen. Conventies keren dat idee om: in plaats van een lange uitleg te lezen, lees je de structuur.
Als een framework (en je team) het eens is over waar dingen horen, wordt de repository navigeerbaar als een stadsraster.
Als je weet dat UI-componenten in components/ gaan, paginaviews in pages/ en API-handlers in api/, dan stop je met vragen “waar is X?” omdat de eerste gok meestal juist is. Zelfs als dat niet zo is, is je zoekruimte beperkt: het is niet ergens—het staat in één van een klein aantal verwachte plekken.
Conventies laten bestandsnamen en symbolen betekenis dragen. Een nieuwkomer kan gedrag afleiden uit locatie en naamgeving:
user.controller behandelt waarschijnlijk requestlogicaUserService-klasse bevat waarschijnlijk businessregelsmigrations/ bevat waarschijnlijk geordende, éénmalig uit te voeren databasewijzigingenDie afleiding verkleint vragen als “leg de architectuur uit” tot kleinere, beantwoordbare vragen (“Mag deze service direct de database aanroepen?”), wat veel makkelijker te documenteren is.
De snelste manier om de kaart te versterken is scaffolding. Starter-templates en generators maken nieuwe features standaard in de “juiste” vorm—mappen, bestandsnamen, boilerplate wiring en vaak tests.
Dit is belangrijk omdat conventies alleen helpen als ze consistent worden toegepast. Een template is een vangrail: het duwt elke nieuwe route, component of module in de verwachte structuur, zodat de codebase leesbaar blijft zonder extra wiki-pagina's.
Als je interne scaffolds onderhoudt, verwijs er dan vanaf een korte onboarding-pagina naar (bijv. /docs/getting-started) en laat de mapstructuur de rest doen.
Frameworkconventies fungeren vaak als stille, ingebouwde instructies. In plaats van een pagina te schrijven die uitlegt “waar dingen horen” of “hoe je dit aansluit”, maakt het framework de keuze al—en leert je team de structuur te lezen.
Rails is beroemd om convention over configuration. Een simpel voorbeeld: maak je een controller OrdersController, dan gaat Rails ervan uit dat er een bijbehorende viewmap is op app/views/orders/.
Die ene conventie kan een stuk documentatie vervangen die anders zou uitleggen:
Resultaat: nieuwe collega's kunnen een pagina toevoegen door het map-patroon te volgen, zonder te hoeven vragen “waar hoort dit bestand?”
Django moedigt een consistente “app”-structuur aan. Als iemand een Django-app ziet, verwacht diegene models.py voor datavormen, views.py voor request-afhandeling en templates/ voor HTML.
Je zou een lange gids kunnen schrijven die de anatomie van je project beschrijft, maar Django's defaults leren dat al. Wil een collega de weergave van een pagina aanpassen, dan kijkt diegene in templates/. Moet data worden aangepast, dan begint men in models.py.
Resultaat: snellere fixes, minder zoekwerk, minder “welk bestand regelt dit?”-berichten.
Next.js vermindert documentatie doordat routing rechtstreeks de mapstructuur weerspiegelt. Maak een bestand op app/about/page.tsx (of pages/about.tsx in oudere setups) en je hebt automatisch een /about-pagina.
Dat scheelt docs over:
Resultaat: onboarding is eenvoudiger—mensen ontdekken de vorm van de site door mappen te scannen.
Rails, Django en Next.js zien er verschillend uit, maar het principe is identiek: gedeelde defaults veranderen projectstructuur in instructies. Als iedereen dezelfde conventies vertrouwt, beantwoordt de codebase veel “hoe doen we dit hier?”-vragen zonder extra documenten te onderhouden.
Frameworkconventies voelen “onzichtbaar” wanneer ze werken. Je kunt raden waar bestanden staan, hoe dingen heten en hoe een request door de app stroomt. Verwarring keert terug als een codebase afdrijft van die gedeelde defaults.
Enkele patronen die vroeg opduiken:
UserService, het andere UsersManager, weer een ander user_serviceDit zijn niet per se fout, maar het betekent dat een nieuwkomer niet meer op de “kaart” van het framework kan vertrouwen.
De meeste breuken met conventies beginnen met een redelijke, lokale optimalisatie: “Deze feature is speciaal, dus we zetten het hier” of “Deze naam leest beter.” Het probleem is dat uitzonderingen besmettelijk zijn. Als de eerste uitzondering er is, gebruikt de volgende ontwikkelaar het precedent:
Op dat punt is de conventie geen conventie meer—het wordt tribal knowledge.
Als conventies vervagen, vertraagt onboarding omdat mensen niet meer kunnen voorspellen waar ze moeten zoeken. Dagelijkse taken duren langer (“Welke van deze mappen is de echte?”), en fouten nemen toe (verkeerde module koppelen, verkeerde naamgevingspatroon gebruiken, logica dupliceren). Teams compenseren door meer synchronisaties te plannen, langere PR-uitleg te schrijven en “quick docs” toe te voegen die verouderen.
Pas alleen aan als je een duidelijke reden hebt—en laat een geschreven notitie achter.
Die notitie kan licht zijn: een korte commentaar bij de ongebruikelijke structuur, of een korte vermelding in /docs/decisions die uitlegt wat veranderde, waarom het de moeite waard is en wat de standaardaanpak voor toekomstig werk moet zijn.
Frameworkconventies kunnen pagina's uitleg wegnemen, maar ze verwijderen geen verantwoordelijkheid. De onderdelen die nog documentatie nodig hebben, zijn die delen waar je project opzettelijk afwijkt van wat de meeste ontwikkelaars zouden aannemen.
Sla het opnieuw uitleggen van standaard frameworkgedrag over. Leg in plaats daarvan beslissingen vast die het dagelijkse werk beïnvloeden:
Voorbeeld: “We gebruiken feature-folders onder /src/features in plaats van laag-mappen (/src/components, /src/services) omdat eigenaarschap aan teams gekoppeld is en cross-team coupling vermindert.” Die ene zin voorkomt weken van langzaam wegdrijven.
Als een uitzondering lokaal belangrijk is, zet de notitie lokaal. Een klein README.md in een map of een korte headercommentaar bovenaan een bestand verslaat vaak een centrale wiki die niemand checkt.
Goede kandidaten:
Houd deze notities kort en actiegericht: wat is anders, waarom is het anders en wat te doen daarna.
Heb één lichtgewicht pagina (meestal in /docs/project-rules.md of de root README) die slechts 5–10 sleutelkeuzes opsomt die mensen zullen struikelen:
Dit is geen volledige handleiding—alleen gedeelde vangrails.
Zelfs met conventies stokt onboarding wanneer mensen de app niet kunnen draaien. Voeg een korte “How to run/test” sectie toe die overeenkomt met de standaardcommando's en je werkelijke setup.
Als het conventionele commando npm test is maar jouw project npm run test:unit vereist, documenteer dat expliciet.
Documentatie blijft accuraat wanneer het onderdeel is van de wijziging. Vraag in reviews: “Introduceert dit een nieuwe uitzondering?” Zo ja, eis dan de bijbehorende notitie (lokale README, Project Rules of root quickstart) in dezelfde pull request.
Als conventies de “gedeelde defaults” van je codebase zijn, maakt automatisering ze echt. In plaats van elke ontwikkelaar te vragen regels uit een wiki te onthouden, maak je de regels uitvoerbaar—zodat het project zichzelf afdwingt.
Een goede setup vangt drift vroeg en stil:
*.spec.ts, describe/it-woordkeuze of vereiste asserts zodat tests consistent lezen.Deze checks vervangen paragrafen van “onthoud alsjeblieft…” door één simpele uitkomst: of de code voldoet aan de conventie of niet.
Automatisering blinkt uit omdat het snel faalt:
De beste regelsets zijn klein en saai. Begin met de frameworkdefaults en voeg alleen toe wat duidelijkheid beschermt (naamgeving, structuur en grenzen). Elke extra regel is weer iets dat mensen moeten leren, behandel nieuwe checks als code: voeg ze toe als ze een terugkerend probleem oplossen en verwijder ze als ze niet meer helpen.
Als een codebase frameworkconventies volgt, kunnen tests meer zijn dan “bewijzen dat het werkt.” Ze kunnen uitleggen wat het systeem hoort te doen, in gewone taal, vlak naast de implementatie.
Een handige regel: één test beschrijft één eind-tot-eind gedrag. Als iemand de testnaam kan scannen en het belofte van het systeem begrijpt, heb je de behoefte aan aparte documentatie verminderd.
Goede tests volgen vaak dit ritme:
Nog beter is naamgeving die de intentie van de gebruiker weerspiegelt:
signing_in_with_valid_credentials_redirects_to_dashboardcheckout_fails_when_shipping_address_is_missingDeze namen zijn documentatie die je niet vergeet bij te werken—want falende tests dwingen het gesprek af.
Acceptatie- (of feature-)tests zijn uitstekend om te documenteren hoe het product zich gedraagt vanuit gebruikerperspectief.
Voorbeelden van gedrag die acceptatietests kunnen beschrijven:
Deze tests beantwoorden de vraag “Wat gebeurt er als ik X doe?”—vaak het eerste dat een nieuwkomer wil weten.
Unit-tests blinken uit als je kleine maar belangrijke regels wilt documenteren:
Ze zijn vooral waardevol wanneer de regel niet direct duidelijk is uit frameworkconventies.
Voorbeelddata kan ook levende documentatie zijn. Een klein, goed benoemd fixture (bv. user_with_expired_subscription) leert het domein sneller dan een paragraaf in een wiki.
De sleutel is terughoudendheid: houd fixtures minimaal, leesbaar en gekoppeld aan één idee, zodat ze betrouwbare voorbeelden blijven in plaats van een tweede systeem om te onderhouden.
Starter-templates (en de generators erachter) zijn de snelste manier om “hoe we hier dingen doen” om te zetten in iets dat mensen daadwerkelijk volgen. In plaats van elk teamlid te vragen zich de juiste mappen, scripts en tooling te herinneren, bak je die keuzes in een repo die meteen correct is.
Alle drie verminderen documentatieschuld omdat de conventie in het startpunt is gecodeerd, niet in een wiki die wegdrijft.
In de praktijk is dit ook waar tools zoals Koder.ai kunnen helpen: wanneer je een nieuwe React-app, Go-backend, PostgreSQL-schema of Flutter-client genereert vanuit een chat-gestuurde workflow, kun je teams op één “gouden pad” houden door de standaardoutput je conventies te laten volgen (en vervolgens de broncode in je repo te exporteren).
De meeste verwarring tijdens onboarding gaat niet over businesslogica maar over waar dingen leven en hoe ze draaien. Een goede template maakt veelvoorkomende taken identiek tussen repos: dezelfde scripts, dezelfde mapnamen, dezelfde check-commando's, dezelfde PR-verwachtingen.
Als je niets anders doet, stem dan af op:
/src, /test, /docs alleen voor uitzonderingen)Houd het klein genoeg dat teams het niet overslaan:
install + dev)test, lint en format scriptsHet grootste risico is het kopiëren van een oude template “omdat het vorig jaar werkte.” Verouderde dependencies, legacy-scripts of achterhaalde patronen verspreiden zich snel als ze in een starter zitten.
Behandel templates als producten: versieer ze, review ze periodiek en werk ze bij als je conventies veranderen. (Als je platform snapshots en rollback ondersteunt—Koder.ai doet dat—gebruik die om starters veilig te itereren zonder ieders baseline te breken.)
Documentatie verminderen betekent niet mensen laten raden. Het betekent de “happy path” zo consistent maken dat de meeste vragen zichzelf beantwoorden, en alleen de echt ongebruikelijke delen optekenen.
Zoek plekken waar mensen herhaaldelijk dezelfde vragen stellen in Slack, PR-opmerkingen, standups of onboarding-sessies. Enkele prompts:
Als je dezelfde vraag twee keer hoort, heb je waarschijnlijk geen extra proza nodig—je hebt een conventie nodig.
Voor elke terugkerende vraag beslis je:
Een nuttige regel: als een afwijking geen echte tijdwinst oplevert of geen reëel risico voorkomt, is het waarschijnlijk de verwarring niet waard.
Houd één korte pagina (bv. /docs/conventions) die opsomt:
Beperk je tot wat iemand in de eerste week nodig heeft. Als het groeit, is dat vaak een teken dat je de codebase eenvoudiger moet maken.
Apps evolueren. Plan een lichte kwartaalreview:
Geef de voorkeur aan frameworkdefaults wanneer mogelijk, en documenteer alleen wat afwijkt—duidelijk, beknopt en op één plek.
Frameworkconventies zijn de standaardpatronen die een framework verwacht dat je volgt—mapstructuur, naamgeving, routing, data-toegang en veelgebruikte commando's. Als je je eraan houdt, kunnen andere ontwikkelaars afleiden waar dingen staan en hoe ze werken zonder project-specifieke documentatie te hoeven lezen.
Omdat het moeilijk is om proza actueel te houden terwijl de codebasis verandert. Documentatie bestaat vooral om:
Conventies dekken de eerste twee door de structuur voorspelbaar te maken.
Nee. Conventies verminderen documentatie over het voor de hand liggende (waar bestanden horen, hoe routes werken), maar je moet nog steeds documenteren wat projectspecifiek is: businessregels, opzettelijke afwijkingen en belangrijke beslissingen. Denk: “minder documentatie, meer waardevolle documentatie.”
Ze standaardiseren de terugkerende “dag één”-vragen:
Als de code een bekend patroon volgt, fungeren de mappen en bestandsnamen als wegwijzers. Een nieuwkomer navigeert op verwachting (bijv. “templates staan in templates/”, “migrations in migrations/”) in plaats van een lange architectuurbeschrijving te moeten lezen die mogelijk verouderd is.
Ze coderen de conventies in defaults zodat mensen niet op geheugen vertrouwen. Goede scaffolds genereren:
Dit voorkomt drift en houdt de “kaart” consistent tussen features.
Je merkt het wanneer ontwikkelaars niet meer kunnen voorspellen waar iets hoort of hoe het heet. Veelvoorkomende signalen:
UserService vs UsersManager vs user_service)Op dat punt compenseert het team met Slack-uitleg, langere PR's en verouderde “quick docs.”
Pas alleen aan als er een helder voordeel is, en laat dan een compact notitie achter die de afwijking uitlegt:
README.md in de ongebruikelijke map/docs/decisions of iets vergelijkbaarsLeg vast wat er veranderde, waarom, en wat de standaardaanpak voortaan moet zijn.
Begin met een kleine, praktische basis:
Houd het compact en eis bij code reviews dat een wijziging die een nieuwe uitzondering introduceert ook de documentatie bijwerkt.
Gebruik automatisering om conventies uitvoerbaar te maken:
Als checks falen tijdens lokale ontwikkeling of in PR's, leren ontwikkelaars de regels direct—en reviewers hoeven minder tijd te besteden aan stijlcontrole.
Als die voorspelbaar zijn, wordt de repo grotendeels vanzelfsprekend.