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:

Beschrijf eerst de waarneembare regressie of gewenste invariant.
Zoek de laag die eigenaar is van die invariant.
Maak de kleinste samenhangende wijziging op die laag.
Voeg een regressietest toe op het laagst mogelijke niveau.
Controleer aangrenzende contracten: database, API, browserstate, DOM-id's en vertalingen.
Werk versienummer, changelog en relevante architectuurpagina bij.
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 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 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.

4.6 KiB Raw Blame History