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.
Elke developer krijgt de vraag als je hebt aangegeven dat je weet wat er gebouwd gaat worden (of als je nog geen flauw idee hebt, als iemand je in 1 minuut een systeem heeft uitgelegd dat minimaal 5 manjaar kost om te bouwen, maar dat terzijde): wanneer is het af?
). Dit omdat in hun ogen, en daar ben ik het wel mee eens, je een meer accuratere schatting krijgt als je er even over kunt nadenken.
Welkom op de blog van 