Talin

Follow

3 jan, 2019 – 7 min read

Een belangrijke vaardigheid voor elke software engineer is het schrijven van technical design docs (TDD’s), ook wel engineering design docs (EDD’s) genoemd. In dit artikel geef ik advies over het schrijven van goede ontwerpdocumenten en welke fouten je moet vermijden.

Eén voorbehoud: verschillende teams zullen verschillende normen en conventies hanteren voor technisch ontwerp. Er is geen industrie-brede standaard voor het ontwerpproces, en dat zou ook niet kunnen, omdat verschillende ontwikkelteams verschillende behoeften zullen hebben, afhankelijk van hun situatie. Wat ik zal beschrijven is een mogelijk antwoord, gebaseerd op mijn eigen ervaring.

Laten we beginnen met de basis: Wat is een technisch ontwerpdocument, en hoe past het in het ontwerpproces?

Een technisch ontwerpdocument beschrijft een oplossing voor een bepaald technisch probleem. Het is een specificatie, of “ontwerp blauwdruk”, voor een software programma of functie.

De primaire functie van een TDD is om de technische details van het werk dat moet worden gedaan aan de leden van het team te communiceren. Er is echter een tweede doel dat net zo belangrijk is: het proces van het schrijven van de TDD dwingt je om je gedachten te ordenen en elk aspect van het ontwerp te overwegen, ervoor zorgend dat je niets hebt weggelaten.

Technische ontwerpdocumenten zijn vaak onderdeel van een groter proces dat typisch de volgende stappen kent:

1. Producteisen worden gedefinieerd. Deze worden meestal weergegeven in een Product Requirements Document (PRD). De PRD specificeert wat het systeem moet doen, vanuit het perspectief van een gebruiker of een externe agent.
2. Technische eisen worden gedefinieerd. De producteisen worden vertaald in technische eisen – wat het systeem moet bereiken, maar nu hoe het dat doet. De output van deze stap is een Technical Requirements Document (TRD).
3. Technisch ontwerp. Dit bevat een technische beschrijving van de oplossing voor de eisen die in de vorige stappen zijn geschetst. De TDD is de output van deze stap.
4. Implementatie. Dit is de fase waarin de oplossing daadwerkelijk wordt gebouwd.
5. Testen. Het systeem wordt getest tegen de PRD en TRD om te verzekeren dat het werkelijk aan de gespecificeerde vereisten voldoet.

Tussen elk van deze stadia is er typisch een herzieningsproces om te verzekeren dat geen fouten werden gemaakt. Als om het even welke fouten, misverstanden, of dubbelzinnigheden worden ontdekt, moeten deze worden gecorrigeerd alvorens aan de volgende stap verder te gaan.

Dit proces is hoogst veranderlijk; de reeks hier vermelde stappen zal van geval tot geval veranderen. Bijvoorbeeld:

• Voor kleinere functies die niet veel complexiteit met zich meebrengen, zullen stap 2 en 3 vaak worden gecombineerd in een enkel document.
• Als de functie een groot aantal onbekenden of een bepaald niveau van onderzoek met zich meebrengt, kan het nodig zijn om een proof-of-concept-implementatie te bouwen alvorens het technisch ontwerp af te ronden.

Dit proces gebeurt ook op verschillende schalen en granulariteitsniveaus. Een PRD / TRD / TDD kan betrekking hebben op het ontwerp van een heel systeem, of slechts een enkele functie. In de meeste omgevingen is het proces ook cyclisch – elke ontwerp/implementatie cyclus bouwt voort op het werk van de vorige.

De scheidslijn tussen TRD en TDD kan soms een beetje wazig zijn. Stel bijvoorbeeld dat je een server ontwikkelt die communiceert via een RESTful API. Als het doel is om te voldoen aan een reeds vastgestelde en gedocumenteerde API, dan maakt de API specificatie deel uit van de vereisten en zou er in de TRD naar moeten worden verwezen. Als, anderzijds, het doel is om een gloednieuwe API te ontwikkelen, dan maakt de API specificatie deel uit van het ontwerp en zou in de TDD moeten worden beschreven. (Het requirements document moet echter nog steeds specificeren wat de API probeert te bereiken.)

Het schrijven van de TDD

Dezer dagen is het gebruikelijk om technische documenten te schrijven in een collaboratief documentsysteem, zoals Google Docs of Confluence; dit is echter geen absolute vereiste. Het belangrijkste is dat er een manier is voor je teamleden om commentaar te kunnen leveren op het document en te wijzen op fouten en omissies.

De meeste TDD’s zijn tussen de één en tien pagina’s. Hoewel er geen bovengrens is voor de lengte van een TDD, zullen zeer grote documenten zowel moeilijk te bewerken als moeilijk te absorberen zijn voor lezers; overweeg het op te splitsen in afzonderlijke documenten die afzonderlijke stappen of fasen van de implementatie vertegenwoordigen.

Diagrammen zijn nuttig; er zijn een aantal online tools die u kunt gebruiken om illustraties in het document op te nemen, zoals draw.io of Lucidchart. U kunt ook offline tools zoals Inkscape gebruiken om SVG-diagrammen te genereren.

Het document moet grondig zijn; idealiter moet het mogelijk zijn voor iemand anders dan de TDD-auteur om het ontwerp te implementeren zoals geschreven. Bijvoorbeeld, als het ontwerp een implementatie van een API specificeert, zou elk API eindpunt moeten worden gedocumenteerd. Als er subtiele ontwerpkeuzes zijn, moeten die worden genoemd.

Vermijd veel voorkomende schrijffouten

De meest voorkomende fout die ik tegenkom in TDDs is waarschijnlijk een gebrek aan context. Dat wil zeggen dat de auteur in zo weinig mogelijk woorden heeft opgeschreven hoe hij het probleem heeft opgelost; maar hij heeft geen informatie gegeven over wat het probleem was, waarom het moest worden opgelost, of wat de gevolgen waren van die specifieke oplossing.

Ook is het belangrijk om in gedachten te houden wie de waarschijnlijke lezer is, en welk niveau van begrip hij heeft. Als u een term gebruikt die de lezer misschien niet kent, wees dan niet bang om er een definitie aan toe te voegen.

Het behoeft nauwelijks betoog dat een goede grammatica en spelling nuttig zijn. Vermijd ook de verleiding van woordspelingen of “leuke” spelling; hoewel programmeurs als klasse graag spelen met taal, heb ik meer dan eens gevallen gezien waar buitensporige frivoliteit uiteindelijk het team verspilde moeite kostte door misverstanden. Het is prima om af en toe humor te gebruiken of kleurrijke, gedenkwaardige namen te kiezen voor functies en systemen, omdat dat mensen helpt ze te onthouden. Maar laat je verlangen om te laten zien hoe slim je bent geen afleiding worden.

Over namen gesproken, kies ze zorgvuldig; zoals Mark Twain ooit schreef: “Kies het juiste woord, niet het achterneefje ervan.” Ingenieurs met een slechte woordenschat hebben de neiging om steeds weer dezelfde algemene termen te gebruiken voor verschillende dingen, wat leidt tot overbelasting en verwarring. Bijvoorbeeld, een klasse “DataManager” noemen is vaag en zegt je niets over wat ze eigenlijk doet; op dezelfde manier kan een package of directory met de naam “utils” vrijwel alles bevatten. Raadpleeg een thesaurus als je een beter woord wilt vinden, of beter nog, een gespecialiseerde synoniem-database zoals WordNet.

TDD Template

Bij het schrijven van een TDD kan het handig zijn om te beginnen met een standaard template. Het volgende is een sjabloon dat ik in een aantal projecten heb gebruikt. Merk op dat dit sjabloon moet worden aangepast waar nodig; u bent vrij om secties die niet van toepassing zijn te verwijderen, extra secties toe te voegen, of koppen een andere naam te geven indien nodig.