De meesten developers houden niet van het schrijven van documentatie. Maar waar we echt een hekel aan hebben, is geen idee hebben van ‘welk stuk code wat doet’ en waarom de code op een bepaalde manier is opgebouwd. Dat is de reden waarom we ons werk moeten documenteren. Daarbij houden we ons aan 'the Agile Manifesto': code die werkt gaat vóór uitgebreide documentatie.

Als eerste moeten we projectdocumentatie niet verwarren met systeemdocumentatie. Projectdocumentatie is alleen geldig voor de duur van het project of zelfs alleen van de 'sprint', terwijl systeemdocumentatie de volledige levensduur van de applicatie moet meegaan. Ten tweede moeten we het documenteren onderdeel maken van onze programmeerroutine, in plaats van een klus die we aan het einde nog ‘even’ doen. Ik vind ook dat de documentatie onderdeel moet zijn van de code en niet afzonderlijk moet worden bijgehouden.

Stel een aantal documentatiestandaarden op (zie de OutSystems Platform Best Practices) en gebruik het Architecture Dashboard om te controleren op naleving daarvan.

Modulenaamgevingsconventie: bepaal een naamgevingsconventie voor Modules en Extensions. Naamgevingsconventies helpen de aard van iedere module en ieder element te tonen, dwingen de verwijzingsarchitectuur af en normaliseren patronen. Zie de cursus designing apps using an architecture framework voor een uitgebreide richtlijn over de naamgevingsconventie en de architectuur die deze ondersteunt.

OSMDb-componentenweergave in Discovery

Geef applicaties een betekenisvol pictogram en een duidelijke omschrijving. Voer ook de omschrijvingen voor alle Modules en Extensions in.

Voorbeeld van een omschrijving van applicatie en module

Maak omschrijvingen verplicht voor Entities, Attributes, Server Actions, Web Blocks en User Roles.

Alle Modules van entiteiten moeten minstens één entiteitsschema bevatten. Bij complexe structuren moet er voor ieder linking concept een entiteitsschema zijn dat dit uitlegt.

Omschrijf complexe logica: voeg een opmerking toe aan delen met een complexe logica, waarin je deze uitlegt. Al na een paar maanden begrijp je waarschijnlijk niets meer van de logica of ben je vergeten waarom je ervoor hebt gekozen het op die manier te implementeren.

Gebruik een Architecture Decision Record (ADR) sjabloon om je ontwerpbeslissingen te documenteren en plaats dit in je applicatie of module, of daar waar dat het beste past. Zie de video Architecture Decision Records in Action voor meer informatie over ADR's.

Code-evaluatie is het systematisch onderzoeken van computerbroncode (ook wel peer review genoemd). De bedoeling ervan is fouten op te sporen die vaak over het hoofd worden gezien bij softwareontwikkeling, zodat de algehele kwaliteit van de software wordt verbeterd. Evaluaties kunnen worden uitgevoerd in verschillende vormen, via formele inspecties bijvoorbeeld of door er informeel doorheen te lopen.

Stel een coderingsstandaard op en maak code-evaluatie onderdeel van je 'Definition of Done'. Een goed startpunt zijn de OutSystems Platform Best Practices.

Documenteer de anti-patterns (design patterns die zijn toegepast in een verkeerde context) die je tegenkomt en controleer erop in de code-evaluaties.

Waarom is testen belangrijk?
Iedereen maakt fouten. Sommige van die fouten zijn niet zo erg, maar andere kunnen heel duur of gevaarlijk worden. Het testen van software is daarom van essentieel belang, omdat het de kwaliteit van het product en het vertrouwen en de tevredenheid van de klant ten aanzien van de applicatie (bron: istqb exam specification) beïnvloedt.

 Testen is een verantwoordelijkheid van het team en iedereen met een andere rol in het team voert een ander type test(s) uit. Ontwikkelaars voeren op hun geïmplementeerde User Stories unittesten uit en de producteigenaar voert testen uit zoals End-to-end of Exploratory testen. Key users zijn cruciaal voor de begeleiding, validatie en acceptatieactiviteiten. De tester of coördinator voor kwaliteitswaarborging plant de testen, valideert de acceptatiecriteria en coördineert de gebruikersacceptatietesten.

Er zijn enkele componenten in OutSystems Forge die kunnen helpen testen te implementeren, uit te voeren en te beheren:

• Test Automator
• Test Framework
• BDD Framework
• Unit Testing Framework

Het valt buiten de reikwijdte van dit artikel om een uitgebreide uitleg te geven van het testen. Volg het aangegeven traject op Becoming a Tester in OutSystems om meer over dit onderwerp te weten te komen.

Gebruik de Forge component Discovery regelmatig (bijvoorbeeld dagelijks of wekelijks) om te controleren of je architectuur voldoet aan de Four Layer architectuur. Daarnaast kun je de Clean Architecture Tool gebruiken voor een beter inzicht in je architectuur.

Er zijn drie regels voor het The Architecture Canvas die je altijd moet volgen voor een goed ontworpen applicatie-architectuur:

1. Geen verwijzingen omhoog.
2. Geen onderlinge verwijzingen tussen modules van de Orchestration layer of de End-user layer.
3. Geen cyclische verwijzingen tussen modules.

Herstel de overtredingen op volgorde van hun impact:

1. Overtredingen door verwijzingen omhoog of zijverwijzingen naar End-user modules: het gebruiken van End-user modules verhindert solide, boomvormige hiërarchieën onder alle End-user modules.
2. Directe cyclische verwijzingen tussen Core modules: minder impact omdat hierdoor kleinere clusters worden gecreëerd, die beperkt zijn tot Core en Library modules.
3. Schendingen door verwijzingen omhoog naar Core modules: slechte isolatie van Libraries, die onverwacht clusters van Core of Library modules met zich meetrekken.
4. Directe cyclische verwijzingen tussen Libraries: impact is meestal beperkt tot de betrokken modules, omdat deze zich onderaan in de hiërarchie bevinden.

Volg de trainingen Architecture Patterns in OutSystems en Validating and refactoring applications om meer te leren over de architectuur en validatie van je applicatie en lees ook de pagina's die vermeld staan op Designing the Architecture of Your OutSystems Applications.

Kwaliteitscontrole is essentieel bij het afleveren van robuuste en onderhoudbare OutSystems applicaties. Voor het verbeteren van de kwaliteit van je software kun je de volgende hulpmiddelen en methoden gebruiken:

• Documentatiestandaarden
• Code-evaluatie
• Testen
• Validatie en refactoring van applicaties

Gebruik deze hulpmiddelen op een verstandige manier. Begin klein en breid uit terwijl je project in omvang toeneemt. De reikwijdte en frequentie van de hulpmiddelen strekt zich uit van een taak voor een ontwikkelaar tot de volledige applicatie en zelfs tot op het niveau van het bedrijf.

En onthoud dit:
Als iets de moeite waard is om te doen, is het de moeite waarde om het goed te doen!

[Met dank aan: Remco Dekkinga en Jacqueline Spits.]