70 lines
4.6 KiB
Markdown
70 lines
4.6 KiB
Markdown
# Onderhoudbaarheid
|
|
|
|
Onderhoudbaarheid betekent hier dat een ontwikkelaar een wijziging kan lokaliseren, de gevolgen kan overzien en het resultaat kan controleren zonder eerst de hele applicatie te herschrijven.
|
|
|
|
## Wat al helpt
|
|
|
|
De applicatie heeft één codebase, één backendproces en één duurzame database. Versies staan centraal in `info.rkt`; schemawijzigingen hebben een oplopende migratieketen. Pagina- en CMapversies zijn volledig en onveranderlijk, waardoor fouten in de actuele toestand niet meteen de historie vernietigen.
|
|
|
|
Backendprocedures hebben vaak een contractcommentaar met doel, preconditie, postconditie en resultaat. De browsercode gebruikt vergelijkbare JSDoc-blokken bij ingewikkelde functies. Frontendbibliotheken zijn vastgepind, zodat een CDN-update niet onverwacht productiegedrag verandert.
|
|
|
|
## Onderhoudsrisico's
|
|
|
|
De grootste risico's zijn concentratie en impliciete koppeling:
|
|
|
|
- `server.rkt` en `wiki.js` kennen veel scenario's;
|
|
- HTML-id's in `index.html` en `$()`-aanroepen in `wiki.js` vormen een compileertijd-onzichtbaar contract;
|
|
- vertaalkeys worden tussen Racket, HTML en JavaScript gedeeld;
|
|
- CMap-documentvelden worden zowel door opslag als editorcode verondersteld;
|
|
- versiestempels staan behalve in `info.rkt` ook in frontenddiagnostiek;
|
|
- de huidige geautomatiseerde testdekking is beperkt tot de nieuwe architectuurimportmodule.
|
|
|
|
Deze koppelingen moeten bij iedere release statisch of geautomatiseerd worden gecontroleerd.
|
|
|
|
## Wijzigingswerkwijze
|
|
|
|
Een onderhoudbare wijziging volgt deze volgorde:
|
|
|
|
1. Beschrijf eerst de waarneembare regressie of gewenste invariant.
|
|
2. Zoek de laag die eigenaar is van die invariant.
|
|
3. Maak de kleinste samenhangende wijziging op die laag.
|
|
4. Voeg een regressietest toe op het laagst mogelijke niveau.
|
|
5. Controleer aangrenzende contracten: database, API, browserstate, DOM-id's en vertalingen.
|
|
6. Werk versienummer, changelog en relevante architectuurpagina bij.
|
|
7. Voer compileer-, JavaScript-, import- en smokecontroles uit.
|
|
|
|
Bij een CMap-interactieregressie hoort bijvoorbeeld eerst een editorcomponenttest of gerichte browser-spike. Een aanpassing in opslagcode is alleen passend wanneer het opgeslagen document onjuist is.
|
|
|
|
## Leesbaarheid als ontwerpkeuze
|
|
|
|
Nieuwe Racket-code kiest expliciete, leesbare constructies boven compacte combinaties van idiomen. Een afzonderlijke `if`, benoemde tussenwaarde of kleine inhoudelijke helper is beter dan een korte expressie waarvan falsy filtering, mutatie en datastructuurkennis tegelijk begrepen moeten worden. Gebruik `λ` voor anonieme procedures.
|
|
|
|
Leesbaarheid betekent niet dat iedere aanroep een wrapper krijgt. Een helper verdient een naam wanneer die naam domeinbetekenis toevoegt, herhaling veilig centraliseert of een testbare grens maakt.
|
|
|
|
Zie [Regels bij het coderen](racket-wiki:code-regels) voor de volledige set.
|
|
|
|
## Versies en compatibiliteit
|
|
|
|
Een release verandert `info.rkt` en alle zichtbare frontendversiestempels. Bestaande databases worden uitsluitend via een nieuwe migratie vooruitgebracht. Een CMap-documentwijziging verhoogt `schemaVersion` en vereist expliciete leescompatibiliteit of migratie; onbekende velden mogen niet zonder besluit verdwijnen.
|
|
|
|
API-contracten worden bij voorkeur compatibel uitgebreid. Wanneer een veld verplicht wordt, moeten oude browserassets en nieuwe backend niet tijdelijk onverenigbaar kunnen worden geserveerd. Cacheversies en deploymentvolgorde horen daarom bij de wijziging.
|
|
|
|
## Documentatie als onderdeel van de code
|
|
|
|
Deze architectuurset staat als bronbestanden in het pakket. De importmodule valideert interne paginalinks, CMap-embeds, nodeverwijzingen en connector-endpoints voordat zij iets schrijft. Daardoor is documentatiesamenhang niet alleen een handmatige afspraak.
|
|
|
|
Een wijziging die een modulegrens, gegevensinvariant, beveiligingsregel, teststrategie of schaalverwachting verandert, is pas afgerond wanneer de bijbehorende pagina is aangepast. Gebruik [Beheer en evolutie](racket-wiki:beheer-en-evolutie) om de set opnieuw te importeren zonder lokale wijzigingen stilzwijgend te overschrijven.
|
|
|
|
## Vermijd voortijdige herbouw
|
|
|
|
Onderhoudbaarheid neemt niet automatisch toe door meer lagen, dependency injection of generieke frameworks. Voor racket-wiki blijft de voorkeur:
|
|
|
|
- directe statische dependencies;
|
|
- gewone Racket-waarden;
|
|
- kleine publieke interfaces;
|
|
- transacties rond echte invarianten;
|
|
- extractie na aantoonbare herhaling of testbehoefte;
|
|
- meting vóór performance-architectuur.
|
|
|
|
Dat houdt de applicatie passend bij haar doel: een begrijpelijke, zelf te beheren wiki en geen platform dat zijn eigen uitbreiding belangrijker maakt dan de inhoud.
|