De kunst van het maken van architectuurdiagrammen

Op enig moment, in elk software project waar we bij betrokken zijn, kan er een noodzaak zijn om architectuurdiagrammen te maken. Of we nu een formeel architectuurmodel volgen (b.v. Kruchten 4+1, Rozanski & Woods, etc) of niet, er is een noodzaak om sommige delen van de applicatie te documenteren door diagrammen te maken. In de software-architectuur worden dergelijke diagrammen gemaakt in overeenstemming met views die betrekking hebben op een specifiek gezichtspunt dat deel zou kunnen uitmaken van een model, maar in het huidige artikel geef ik er de voorkeur aan om het bij de term architectuurdiagram te houden en niet erg formeel te zijn; het is niet de bedoeling dat alle andere aspecten hier worden behandeld.

Gebaseerd op mijn ervaring als software-architect en technisch trainer, zijn er veel discrepanties tussen projecten en binnen het projectteam van ontwikkelaar tot ontwikkelaar in de manier waarop architectuurdiagrammen worden gemaakt. Ik zag veel problemen met betrekking tot inconsistentie, fragmentatie, en granulariteit van de weergegeven informatie en het uiterlijk van de diagrammen. In vergelijking met een architectuurmodel dat formeel en gestandaardiseerd moet zijn, zijn de diagrammen niet noodzakelijkerwijs geformaliseerd of volgen ze een specifieke standaard.

Desalniettemin moeten diagrammen zelf-beschrijvend zijn, consistent, accuraat genoeg en verbonden met de code. Dat is waarom het belangrijk is dat elke architect of software engineer vertrouwen op een aantal richtlijnen bij het maken van architectuurdiagrammen, omdat ze de gemeenschappelijke basis van het communiceren van de architectuur van de toepassing in de tijd (bijvoorbeeld structuur, elementen, relaties, eigenschappen, principes) en over verschillende belanghebbenden met verschillende technische achtergronden en zorgen.

Valkuilen bij het ontwerpen van architectuurdiagrammen

Voordat we dieper ingaan op mogelijke problemen, wil ik graag een analogie met een Engels idioom dat zegt “een beeld is meer waard dan duizend woorden”. Volgens deze wiki-uitleg, “verwijst het naar de notie dat een complex idee kan worden overgebracht met slechts een enkel stilstaand beeld of dat een beeld van een onderwerp de betekenis of essentie ervan effectiever overbrengt dan een beschrijving dat doet”. Hetzelfde concept geldt voor een architectuurdiagram: als het meer vragen oproept dan antwoorden geeft, is het diagram niet goed gemaakt. Laat een architectuurdiagram geen duizenden woorden of verduidelijkingen vereisen!

Exemplaar van een onjuist architectuurdiagram. Het lijdt aan de meeste van de hieronder beschreven problemen

Laten we nu een lijst van valkuilen doorlopen die het proces van het correct maken van architectuurdiagrammen kunnen belemmeren.

Wat betekent een doos of vorm?

• Het gebruik van een doos of vorm die niet goed gedocumenteerd is, kan leiden tot meerdere interpretaties. Het kan worden geassocieerd met een stuk gegevens, een hoop code of een proces. Alleen al een eenvoudige box in een diagram kan veel twijfels oproepen en het is erg belangrijk om dit te voorkomen door expliciet details toe te voegen over de betekenis van de box of shape in de legenda van het diagram.

Wat betekenen de verschillende randen van een vorm?

• Elke rand van een vorm (b.v. gestippeld, gestippeld, enz.) kan verkeerd worden begrepen in het geval van een slecht diagram. Verwijst een bepaalde rand naar een bepaald type component (bijv. een stippellijn verwijst naar een container, een microservice, een laag, enzovoort), of is het gewoon de voorkeur van de ontwerper om een rijke uitstraling te hebben? Voorkom dergelijke verwarring door in het legenda-diagram nauwkeurige details te verstrekken wanneer u meerdere of niet-standaardranden kiest.

Wat betekent een lijn of een pijl?

• Een lijn of een pijl kan worden geïnterpreteerd als een gegevensstroom (bijv. gegevensstromen van systeem A naar systeem B) of als een relatie tussen elementen (bijv. component A is afhankelijk van component B). In de meeste gevallen lopen de relaties of gegevensstromen die door pijlen worden weergegeven niet in dezelfde richting en is het belangrijk dit expliciet in de legenda van het diagram te vermelden.

Wat is het communicatie-/associatietype dat door een lijn of pijl wordt aangegeven?

• Zelfs als de lijn verwijst naar een gegevensstroom of een relatie tussen componenten, moet het communicatietype (bijv. in het geval van een gegevensstroom) of het associatietype (bijv. in het geval van een relatie) dat door die lijn of pijl wordt aangeduid, gedetailleerd worden weergegeven. Als de lijn bijvoorbeeld een gegevensstroom voorstelt, kan de communicatie synchroon of asynchroon zijn, maar als de lijn naar een relatie verwijst, kan deze worden weergegeven door een afhankelijkheid, overerving, implementatie, enz. Al deze details moeten aanwezig zijn in de legenda van het diagram.

Wat betekent die kleur?

• Het hebben van een ‘perrot’ policolor diagram (bijv. meerdere kleuren voor boxen, lijnen) zonder een goed gedocumenteerde bedoeling kan meerdere vragen oproepen (bijv. waarom zijn sommige boxen groen en andere rood? Waarom zijn sommige lijnen zwart en andere blauw?) Het kleurenschema is minder belangrijk in een diagram, en het gebruik van een groot aantal kleuren levert niet al te veel extra inhoud of waardevolle informatie op. Een diagram kan ook zelfverklarend en goed ontworpen zijn door gewoon zwarte en witte kleuren te gebruiken, tenzij er een strikte beperking is om sommige delen van het diagram te benadrukken door onderscheidende kleuren te gebruiken. In ieder geval is het altijd beter om het eenvoudig te houden wat betreft de gebruikte kleuren, maar als dat niet het geval is, vergeet dan niet om de keuze te detailleren.

Ontbrekende relaties tussen diagramelementen of geïsoleerde entiteiten

• Ontbrekende relaties tussen elementen of geïsoleerde entiteiten in een diagram kunnen een aanwijzing zijn van onvolledigheid. Zowel vanuit structureel als gedragsperspectief moet elk element of elke entiteit een relatie hebben (weergegeven door een lijn of pijl) met een ander deel van het systeem dat door een ander element wordt weergegeven.

Misleidende/ongedocumenteerde acroniemen of te vage/generieke termen

• Bij het gebruik van een label voor een element in een diagram wordt aanbevolen geen misleidende of ongedocumenteerde acroniemen te gebruiken die tot verwarring zouden kunnen leiden. Een opeenvolging van letters (bijv. TFH, RBPM) betekent niets zonder een goede verklaring op het diagramelement of, nog beter, in de diagramlegenda (bijv. TFH – ticket feed handler, RBPM – rates business process manager).

• Een ander kenmerk van het benoemen van diagramelementen heeft betrekking op extreem vage of generieke termen (bijv. business logica, integratielogica) die niet al te veel waardevolle informatie opleveren omdat hun namen niet goed zelf-beschrijvend zijn. Dit probleem kan zich ook op codeniveau voordoen, en de suggestie zou zijn om altijd zelfverklarende en suggestieve namen te gebruiken door de principes van schone code te volgen.

Het benadrukken van technologieën, raamwerken, programmeer- of scripttalen, IDE of ontwikkelmethodologie op diagrammen

• Architectureel ontwerp is niet gerelateerd aan of fundamenteel gebaseerd op een technologie, raamwerk, programmeer- of scripttaal, IDE of ontwikkelmethodologie. Al deze zaken komen later in het proces om te helpen de architectuur op te bouwen, maar ze staan niet centraal. Ze mogen niet worden opgenomen in de diagrammen, maar moeten worden vermeld in de architectonische beschrijving, inclusief de beweegredenen om ze te kiezen.

Runtime- en statische elementen in hetzelfde diagram mengen

• Runtime-elementen (bijv. threads, processen, virtuele machines, containers, services, firewalls, data repositories, enz. Er zijn speciale diagramtypen (bijv. concurrency diagram, deployment diagram) die primair zijn gericht op runtime-elementen en het is belangrijk om onderscheid te maken tussen deze twee categorieën elementen en om deze zo veel mogelijk te vermijden.

Aannames maken als “ik zal dit mondeling beschrijven”, en “ik zal het later uitleggen”

• Alles wat niet door het diagram zelf wordt beschreven, ontbreekt, en er is geen ruimte om mondelinge details te geven om een diagram aan te vullen. Waarom? Omdat alle mondelinge toelichtingen die niet in het diagram zijn opgenomen verloren gaan, en later, wanneer andere belanghebbenden (b.v. ontwikkelaars, architecten) het diagram zullen lezen, zij niet op de hoogte zullen zijn van deze toelichtingen. Probeer alle noodzakelijke details in een diagram op te nemen om te voorkomen dat er verdere verduidelijkingen nodig zijn.

Conflicterende detailniveaus of gemengde abstracties

• Het toevoegen van elementen met betrekking tot verschillende abstractieniveaus in hetzelfde diagram kan conflicterend zijn, omdat ze vanuit verschillende perspectieven worden bekeken. Bijvoorbeeld, het toevoegen van componenten aan een architectonisch contextdiagram of klassen aan een implementatiediagram zou kunnen afwijken van het doel van het diagram zelf. Probeer bij het maken van een diagram hetzelfde abstractieniveau aan te houden.

Onoverzichtelijke of te vage diagrammen die te veel of te weinig detail proberen weer te geven

• “Everything should be made as simple as possible, but no simpler” is een bekende uitspraak van Albert Einstein. Dit geldt ook voor architectuurdiagrammen; het niveau en de granulariteit van de vastgelegde informatie moeten zinvol worden gekozen. Dit is geen eenvoudige zaak; het hangt af van het gebruikte architectuurmodel, de ervaring van de architect en de complexiteit van het systeem.

Richtlijnen voor het maken van architectuurdiagrammen

Naast de bovengenoemde valkuilen, die deel moeten uitmaken van een checklist om ze te vermijden, zijn er ook algemene richtlijnen voor het maken van de juiste diagrammen:

Kies het optimale aantal diagrammen

• Zoals Philippe Kruchten zei: “Architectuur is een complex beestje. Het gebruik van een enkele blauwdruk om architectuur weer te geven resulteert in een onbegrijpelijke semantische puinhoop.” Om moderne systemen te documenteren kunnen we niet eindigen met slechts één soort diagram, maar bij het maken van architectuurdiagrammen is het niet altijd rechtlijnig welke diagrammen te kiezen en hoeveel ervan te maken. Er zijn meerdere factoren om rekening mee te houden alvorens een beslissing te nemen; bijvoorbeeld de aard en de complexiteit van de architectuur, de vaardigheden en ervaring van de software architect, de beschikbare tijd, de hoeveelheid werk die nodig is om ze te onderhouden, en wat zinvol is of nuttig is om tegemoet te komen aan de bezorgdheden van de stakeholders. Zo zal een netwerkingenieur waarschijnlijk een expliciet netwerkmodel willen zien met hosts, communicatiepoorten en protocollen; een databasebeheerder is bezorgd over hoe het systeem de gegevens manipuleert, beheert en distribueert, enz. Op basis van al deze aspecten wordt aanbevolen om het optimale aantal diagrammen te kiezen, wat dat aantal ook moge zijn.
• Als er te weinig diagrammen zijn (b.v. under-documenting), zouden delen van de architectuur verborgen of ongedocumenteerd kunnen blijven; aan de andere kant, als er te veel zijn (b.v.

Bewaar structurele en semantische consistentie tussen diagrammen

• Elk diagram moet consistent zijn met de andere in termen van boxen, vormen, randen, lijnen, kleuren, etc. De structurele look en feel zou hetzelfde moeten zijn en iedere stakeholder zou geen moeilijkheden moeten hebben om diagrammen te begrijpen die door verschillende ontwikkelaars binnen een team zijn gemaakt. Idealiter houdt men vast aan een gemeenschappelijke diagramtool en hergebruikt deze in alle projecten.
• Vanuit semantisch oogpunt moeten al deze diagrammen periodiek worden gesynchroniseerd met de laatste code veranderingen en tussen deze diagrammen onderling, omdat een verandering in een diagram gevolgen kan hebben voor andere diagrammen. Dit proces kan handmatig of automatisch in gang worden gezet met behulp van een modelleertool. De laatste methode heeft de voorkeur, maar dit hangt af van project tot project, in alle gevallen is het de bedoeling om consistentie te behouden tussen diagrammen en code, onafhankelijk van de methode of het gereedschap. Simon Brown zei “diagrammen zijn niet nuttig voor architectonische verbetering als ze niet verbonden zijn met de code”, wat het idee van semantische consistentie benadrukt.

Voorkom fragmentatie van diagrammen

• Het hebben van meerdere diagrammen kan de architectonische beschrijving moeilijk te begrijpen maken, maar ook een aanzienlijke inspanning in het onderhoud ervan. Als neveneffect zou fragmentatie kunnen optreden (bijv. twee of meer diagrammen illustreren hetzelfde kwaliteitsattribuut – prestatie, schaalbaarheid, enz. – maar elk van hen is afzonderlijk onvolledig). In dergelijke gevallen is het aan te bevelen om ofwel de diagrammen die geen relevante kwaliteitsattributen weergeven (gekoppeld aan architectonisch significante requirements) te verwijderen of, nog beter, diagrammen samen te voegen (bijv. concurrency en deployment).

Bewaar traceerbaarheid tussen diagrammen

• Om de geschiedenis te kunnen controleren, vergelijkingen te kunnen maken tussen verschillende diagram versies en gemakkelijk terug te kunnen gaan naar een vorige versie is ook belangrijk. Het gebruik van een modelleertool die dat niet toestaat, kan een belemmering zijn. De laatste trends in de industrie gaan uit van het gebruik van een eenvoudige en intuïtieve platte tekst taal om daaruit de diagrammen te genereren, hetgeen het probleem van de traceerbaarheid lijkt op te lossen. Een ander voordeel van een dergelijke aanpak is dat deze impliciet zorgt voor een homogene structurele consistentie tussen diagrammen.

Leggenda’s toevoegen naast architectuurdiagrammen

• Als u geen standaard architectuur beschrijvingstaal volgt (b.v. UML, ArchiMate), detailleer dan elk onderdeel van het diagram in de legenda (b.v. boxen, vormen, randen, lijnen, kleuren, acroniemen, etc).
• Als dit niet het geval is, voeg dan in de legenda gewoon de architectonische beschrijvingstaal als sleutel toe en er is geen noodzaak voor extra uitleg, omdat elke lezer die taalspecificaties zal volgen om het diagram te begrijpen.

Maakt de architectonische beschrijvingstaal (b.v. UML, ArchiMate, etc.) een verschil?

Er zijn veel meningen over welke de juiste beschrijvingstaal is die in het project moet worden gebruikt. Sommige mensen zouden kunnen aanvoeren dat UML star is en niet flexibel genoeg om het architectonisch ontwerp te modelleren, een standpunt waar ik het mee eens ben. Niettemin kan het in sommige gevallen meer dan voldoende zijn om de fundamenten van een architectuur te documenteren zonder te vertrouwen op uitbreidingsmogelijkheden van UML, zoals profielen en stereotypen. Als we kijken naar andere beschrijvingstalen, zien we dat ArchiMate krachtiger en geschikter is voor het modelleren van bedrijfssystemen in vergelijking met UML; er is ook BPMN, dat speciaal gericht is op bedrijfsprocessen, enz. De vergelijkingen kunnen nog wel even doorgaan, maar ik ben niet van plan een diepgaand overzicht te geven, omdat dit niet het doel is van dit artikel.

Het hebben van een architectuur beschrijvingstaal die uitgebreid en flexibel genoeg is, is een grote stap voorwaarts en dit zou een solide criterium moeten zijn bij de keuze ervan. Maar vanuit mijn perspectief ligt de werkelijke oorzaak ergens anders en heeft te maken met het feit dat architectuurdocumentatie helemaal niet wordt gemaakt. Mensen vinden het vaak saai, nutteloos of zinloos. Het aantal softwareprojecten zonder, of met onjuiste documentatie, is enorm. Ik denk niet dat mensen zich intensief bezighouden met het maken van architectuurdiagrammen met behulp van een onjuiste beschrijvingstaal, en als ze die zouden vervangen door een betere, zouden de resultaten heel anders zijn. Nee, mensen maken geen architectuurdocumentatie (inclusief architectuurdiagrammen), en erger nog, de meesten van hen hebben geen idee hoe ze die op de juiste manier moeten maken. Dit zijn de dingen die we eerst moeten aanpakken- begrijpen waarom documentatie belangrijk is en hoe je het op de juiste manier maakt (door software ingenieurs op te leiden); dan komt de selectie van de juiste gereedschappen vanzelf.

Hoe kunnen diagrammen up-to-date worden gehouden als het systeem wordt ontwikkeld, en veranderingen in de architectuur materialiseren

Er zijn een paar benaderingen om diagrammen up-to-date te houden; hieronder zal ik er drie uitlichten. De eerste optie, en de gemakkelijkste, zou zijn om diagrammen automatisch te genereren uit de broncode, die de grondwaarheid is. Dit garandeert dat ze allemaal consistent zijn met de code. Jammer genoeg is dit met de bestaande tools nog niet volledig mogelijk (tenminste voor zover ik weet), vermits de huidige tools geen enkel type accuraat en betekenisvol diagram kunnen maken enkel op basis van de broncode, zonder aanzienlijke manuele tussenkomst. Len Bass zei “de ideale ontwikkelomgeving is er een waarvoor de documentatie in principe gratis beschikbaar is met een druk op de knop”, impliciet het automatisch genereren van de diagrammen, maar dat punt hebben we nog niet bereikt.

De tweede benadering zou zijn om eerst de diagrammen te ontwerpen met behulp van een speciaal gereedschap dat dan de broncode skeletten genereert (b.v. componenten/pakketten met grenzen, API’s) die later door ontwikkelaars worden gebruikt om de code in te vullen. Op deze manier moet elke verandering in de architectuur worden getriggerd vanuit het diagram zelf, dat automatisch het code skelet zou kunnen regenereren of bijwerken.

Het laatste geval houdt in dat de diagrammen handmatig worden bijgewerkt telkens wanneer een nieuwe functie – die een impact heeft op het architectuur ontwerp – wordt geïmplementeerd. Om er zeker van te zijn dat alle veranderingen in de code worden gereflecteerd in de diagrammen, wordt aanbevolen om het bijwerken van diagrammen onderdeel te laten zijn van de definitie van gedaan in het ontwikkelproces. Dit scenario wordt minder aanbevolen omdat het gemakkelijk zou kunnen leiden tot verouderde of inconsistente diagrammen (bijv. ontwikkelaars vergeten vaak of zijn niet in de stemming om diagrammen bij te werken) en helaas gebeurt dit nog steeds in een meerderheid van de projecten.

Rekening houdend met bestaande tools, is mijn aanbeveling om een mix te hebben; om automatisch en handmatig gemaakte diagrammen te mengen. Probeer bijvoorbeeld automatisch diagrammen te genereren, die redelijk kunnen worden weergegeven door tools die zijn gebaseerd op broncode zonder al te veel ruis (bijv. te rommelig of zinloze informatie). In deze categorie kunnen we diagrammen opnemen met een hoge mate van veranderlijkheid (b.v. meer vatbaar voor frequente ontwikkelingswijzigingen, gewoonlijk met een lagere abstractie) of, in tegendeel, statische diagrammen. Sommige van dergelijke diagrammen zouden kunnen verwijzen naar context diagrammen, referentie architectuur diagrammen, pakket diagrammen, klasse diagrammen, entiteit diagrammen, enz. Niettemin is het in sommige gevallen niet duidelijk op basis van alleen de broncode hoe het systeem voldoet aan bepaalde kwaliteitsattributen (b.v. beschikbaarheid, schaalbaarheid, prestaties), zodat het automatisch creëren van diagrammen geen afdoende optie is. Het moet worden aangevuld met handmatig gemodelleerde diagrammen. Enkele voorbeelden van dergelijke diagrammen zijn sequentiediagrammen, toestandsdiagrammen, concurrency diagrammen, deployment diagrammen, operationele diagrammen, enz.

Welke complicaties (of vereenvoudigingen) ontstaan er voor architectuurdiagrammen bij het omgaan met moderne architecturen (bijv.bv. microservices)?

Microservices of een andere moderne architectuurstijl (bv. serverless, event driven) stuurt alleen de structuur van het systeem aan, hoe de componenten met elkaar communiceren (bv. relaties tussen hen) en welke principes hen regeren. Persoonlijk denk ik niet dat de architectuurstijl de rationale of concepten rond het maken van de diagrammen (en impliciet de architecturale beschrijving) zou moeten veranderen, noch wat ze zouden moeten vastleggen. Niettemin, wanneer we spreken over moderne systeemarchitecturen, die gewoonlijk hogere niveaus van complexiteit hebben in vergelijking met oude en klassieke systemen (b.v. monolith), dan hebben zij zeker een invloed op de architectuurbeschrijving en impliciet op de diagrammen, in die zin dat er meerdere overwegingen zijn om voor te zorgen. Zulke overwegingen kunnen betrekking hebben op het begrijpen van het aantal gedistribueerde componenten (b.v. gedistribueerde micro-services), het type van elke component, hoe componenten met elkaar communiceren (b.v. grenzen, API’s, berichten), hun levenscyclus en wie eigenaar is van elke component.

Terwijl met al deze rekening wordt gehouden, moeten standaard weergaven worden overwogen die systeemdecompositie, -ontwikkeling, -implementatie en -operabiliteit vastleggen. Stel je bijvoorbeeld een systeem voor met een indrukwekkend aantal microservices; in zo’n geval zou het aantal diagrammen aanzienlijk kunnen toenemen omdat elke microservice uiteindelijk zijn eigen set diagrammen zou kunnen hebben. Problemen met betrekking tot consistentie (bijv. het veranderen van de API van een dienst heeft gevolgen voor andere X diensten, daarom moeten alle diagrammen worden bijgewerkt), fragmentatie (bijv. hoge beschikbaarheid of prestaties tussen gedistribueerde diensten is niet geconsolideerd in een diagram) of transversale kwesties (bijv. wie is verantwoordelijk voor het illustreren, op een geconsolideerde manier, van aspecten zoals monitoring of beveiliging over het gehele systeem elementen) kunnen niet gemakkelijk worden behandeld. Bovendien kunnen er uitdagingen zijn in verband met de coëxistentie en samenwerking van teams tijdens de ontwikkeling van het project, en zelfs daarna, om het in stand te houden.

Samenvattend, moderne systemen met complexe architecturen kunnen extra zorgen met zich meebrengen die zelfs op het niveau van de diagrammen tot complicaties kunnen leiden.

Over de auteur

Ionut Balosin is een software-architect en onafhankelijk technisch trainer. Hij is een regelmatige spreker op software-ontwikkeling conferenties en meetups over de hele wereld, het leveren van presentaties, trainingen en workshops. Kijk voor meer informatie op zijn website.