Het technisch ontwerp

In het kader van Agile development wordt er gediscussieerd over de noodzaak van technische documentatie (het TO). En imho: dat is goed: want niets zo verschillend in kwaliteit, bruikbaarheid en gewicht als een technisch ontwerp, dus een beetje discussie er over kan mijns inziens geen kwaad.
Nou denk ik dat veel mensen die hebben gewerkt met TO’s van 8 kg of meer het wel met de Agile gedachte eens zullen zijn: daar heb je niet zo veel aan. Je kunt onmogelijk alles onthouden, en het is voor de makers van een dereglijk TO zo’n klus om alles te beschrijven dat voor sommige zaken toch nog wel eens een shortcut wordt genomen.
Nou zie als developer veel soorten TO’s, en het grappige is dat het bij elk bedrijf weer anders is. Bij het vorige project moest alles van te voren worden opgeschreven: de WSDL, de indexen, de triggers, het verwachte aantal records per tabel etc., en op het huidige project worden alleen de code wijzigingen achteraf gedocumenteerd. Wat echter niet vaak in een TO naar voren komt zijn design- en code keuzes: waarom zijn bepaalde beslissingen genomen, waarom zijn bepaalde stukken code op een bepaalde manier geschreven en wat betekenen bepaalde tabellen en velden in de database.

Nu, vers op een nieuw project, zit ik weer naar een stuk query te kijken waar een hele stapel joins wordt gebruikt, maar geen enkele documentatie beschikbaar is. Waarbij ik me dus afvraag: waarom moet de verbandcode gelijk zijn aan 8120995, de actie gelijk zijn aan 2 en de vId <> -1 om deze set van personen op te halen?
En wat is het verschil tussen de pId, de vId, de Mid, en de nId? De ‘antwoorden’ die ik wel hier op papier heb staan is dat de vorige developer vijf files heeft aangepast, compleet met de melding dat hij voor een class property een getter en een setter heeft geschreven, en een private field. En dat geeft me nou net weer geen enkele informatie waar ik wat aan heb.

Wat me een aardig uitgangspunt lijkt voor een TO is: documenteer je conclusies en waar nodig je keuzes en het denkproces: Wat is de verbandcode, en wat betekenen de codes, zijn die intern gekoppeld aan een enum? Gebruik gerust meer dan 3 karakters voor je veldnamen, en leg uit wat ze betekenen. Besteed geen tijd aan het documenteren van het veld ‘achternaam’ bij je class Persoon, en ook bij ‘huisnummertoevoeging’ kan ik me wel wat voorstellen. Leg wel uit waarom je bepaalde data cacht, en als je denkt: ik codeer hier een veldje bij dat het onderscheid maakt tussen A en B, typ dat er dan wel even bij.

Moraal van het verhaal: houd je niet vast aan een alles of niets strategie bij het schrijven van een TO, maar schrijf op wat je brainwaves waren om een ander de kans te gunnen je gedachten te volgen, en schrijf niet op dat het verwachte verloop van het aantal records in de tabel ‘geslacht’ in de aankomende 5 jaar waarschijnlijk nul zal zijn.

One thought on “Het technisch ontwerp

  1. Een interessante post Michel. Mijn ervaring is vergelijkbaar. Het probleem zit hem in het feit dat als je geen richtlijnen stelt er niet iets is dat controleerbaar is. Ik kan me namelijk heel goed voorstellen dat als je zegt documenteer de beslissingen die je hebt genomen. Echter in organisaties die het Technisch Ontwerp formeel goedgekeurd willen hebben zullen hier niet happig op zijn. Hoe moeten ze nu controleren dat je de beslissingen die je hebt genomen allemaal gedocumenteerd zijn?

    Eigenlijk is dan de vervolgvraag: In hoeverre wil je een Technisch Ontwerp formeel goedgekeurd hebben?
    Volgens mij is het Technisch Ontwerp nogal aan verandering onderhevig, waarbij met name de laatste 20% pas de dag voor oplevering definitief zal zijn. Wel denk ik dat het goed is om een Technisch Ontwerp te laten reviewen door een Software Architect zodat hij kan inzien of de genomen beslissingen passen binnen de ICT strategie van het bedrijf. Misschien moet de Software Architect gewoon deelnemer zijn van het project, al is het maar voor 8 uur per week.

    Het Technisch Ontwerp blijft een interessant onderwerp van discussie. Vanuit verschillende rollen zijn er nu eenmaal andere verwachtingen.

    – Mark

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s