Engineering Insights
En vigtig færdighed for enhver softwareingeniør er at skrive tekniske designdokumenter (TDD’er), også kaldet engineering designdokumenter (EDD’er). Her i denne artikel giver jeg nogle råd til at skrive gode designdokumenter, og hvilke fejl du skal undgå.
En advarsel: Forskellige teams vil have forskellige standarder og konventioner for teknisk design. Der findes ingen standard for designprocessen i hele branchen, og det kan der heller ikke være, da forskellige udviklingsteams vil have forskellige behov afhængigt af deres situation. Det, jeg vil beskrive, er et muligt svar baseret på min egen erfaring.
Lad os starte med det grundlæggende: Hvad er et teknisk designdokument, og hvordan passer det ind i designprocessen?
Et teknisk designdokument beskriver en løsning på et givet teknisk problem. Det er en specifikation eller et “design blueprint” for et softwareprogram eller en funktion.
Den primære funktion af et TDD er at kommunikere de tekniske detaljer i det arbejde, der skal udføres, til medlemmerne af teamet. Der er dog et andet formål, som er lige så vigtigt: processen med at skrive TDD’en tvinger dig til at organisere dine tanker og overveje alle aspekter af designet og sikre, at du ikke har udeladt noget.
Tekniske designdokumenter er ofte en del af en større proces, som typisk har følgende trin:
- Produktkravene defineres. Disse vil typisk være repræsenteret af et produktkravsdokument (PRD). PRD’et specificerer, hvad systemet skal gøre, set fra en brugers eller ekstern agents perspektiv.
- Tekniske krav defineres. Produktkravene oversættes til tekniske krav – hvad systemet skal udføre, men nu også hvordan det gør det. Resultatet af dette trin er et dokument om tekniske krav (TRD).
- Teknisk design. Dette indeholder en teknisk beskrivelse af løsningen på de krav, der er skitseret i de foregående trin. TDD’et er resultatet af dette trin.
- Implementering. Dette er det trin, hvor løsningen rent faktisk bygges.
- Test. Systemet testes i forhold til PRD og TRD for at sikre, at det faktisk opfylder de specificerede krav.
Mellem hvert af disse trin er der typisk en gennemgangsproces for at sikre, at der ikke er begået fejl. Hvis der opdages fejl, misforståelser eller tvetydigheder, skal disse rettes, inden man går videre til næste trin.
Denne proces er meget variabel; det sæt trin, der er anført her, vil ændre sig fra sag til sag. For eksempel:
- For mindre funktioner, der ikke involverer en stor kompleksitet, vil trin 2 og 3 ofte blive kombineret i et enkelt dokument.
- Hvis funktionen involverer et stort antal ubekendte eller et vist niveau af forskning, kan det være nødvendigt at konstruere en proof-of-concept-implementering, før det tekniske design færdiggøres.
Denne proces sker også på forskellige skalaer og granularitetsniveauer. Et PRD / TRD / TDD kan vedrøre udformningen af et helt system eller blot en enkelt funktion. I de fleste miljøer er processen også cyklisk – hver design/implementeringscyklus bygger på arbejdet i den foregående.
Grænsen mellem TRD og TDD kan til tider være en smule sløret. Lad os for eksempel antage, at du udvikler en server, der kommunikerer via et RESTful API. Hvis målet er at overholde et allerede etableret og dokumenteret API, så er API-specifikationen en del af kravene og bør refereres i TRD’en. Hvis målet derimod er at udvikle et helt nyt API, er API-specifikationen en del af designet og bør beskrives i TDD’en. (Kravsdokumentet skal dog stadig specificere, hvad API’et forsøger at opnå.)
Skrivning af TDD
Det er i dag almindelig praksis at skrive tekniske dokumenter i et samarbejdssystem, f.eks. Google Docs eller Confluence; dette er dog ikke et absolut krav. Det vigtige er, at der er en måde, hvorpå dine teammedlemmer kan komme med kommentarer til dokumentet og påpege fejl og udeladelser.
De fleste TDD’er er på mellem en og ti sider. Selv om der ikke er nogen øvre grænse for længden af en TDD, vil meget store dokumenter både være vanskelige at redigere og svære at absorbere for læserne; overvej at opdele det i separate dokumenter, der repræsenterer de enkelte trin eller faser af implementeringen.
Diagrammer er nyttige; der findes en række onlineværktøjer, som du kan bruge til at indlejre illustrationer i dokumentet, f.eks. draw.io eller Lucidchart. Du kan også bruge offline værktøjer som Inkscape til at generere SVG-diagrammer.
Dokumentet skal være grundigt; ideelt set skal det være muligt for en anden end TDD-forfatteren at implementere designet som skrevet. Hvis designet f.eks. specificerer en implementering af et API, bør hvert API-slutpunkt dokumenteres. Hvis der er subtile designvalg, bør de nævnes.
Undgå almindelige skrivefejl
Den mest almindelige fejl, som jeg støder på i TDD’er, er nok mangel på kontekst. Det vil sige, at forfatteren med så få ord som muligt har skrevet ned, hvordan han/hun har løst problemet; men han/hun har ikke medtaget nogen oplysninger om, hvad problemet var, hvorfor det skulle løses, eller hvad konsekvenserne var af at vælge den pågældende løsning.
Det er også vigtigt at huske på, hvem den sandsynlige læser er, og hvilket forståelsesniveau han/hun har. Hvis du bruger et begreb, som læseren måske ikke kender, skal du ikke være bange for at tilføje en definition af det.
Det behøver næppe at blive sagt, at god grammatik og stavning er en hjælp. Undgå også fristelsen til ordspil eller “sød” stavning; selv om programmører som klasse har en tendens til at kunne lide at lege med sproget, har jeg set mere end ét tilfælde, hvor overdreven frivolitet endte med at koste holdet spildte kræfter på grund af misforståelser. Det er helt i orden at bruge lejlighedsvis humor eller vælge farverige, mindeværdige navne til funktioner og systemer, da det hjælper folk til at huske dem. Men lad ikke dit ønske om at vise, hvor klog du er, blive en distraktion.
Apropos navne, så vælg dem med omhu; som Mark Twain engang skrev: “Vælg det rigtige ord, ikke dets grandfætter.” Der er en tendens til, at ingeniører med dårligt ordforråd bruger de samme generiske udtryk igen og igen for forskellige ting, hvilket fører til overbelastning og forvirring. At navngive en klasse “DataManager” er f.eks. vagt og fortæller intet om, hvad den egentlig gør; på samme måde kan en pakke eller mappe med navnet “utils” indeholde stort set hvad som helst. Konsulter en thesaurus, hvis du har brug for at finde et bedre ord, eller endnu bedre, en specialiseret synonymdatabase som WordNet.
TDD-skabelon
Når du skriver en TDD, kan det være nyttigt at starte med en standardskabelon. Følgende er en skabelon, som jeg har brugt i en række projekter. Bemærk, at denne skabelon bør tilpasses efter behov; det står dig frit for at slette afsnit, der ikke er relevante, tilføje yderligere afsnit eller omdøbe overskrifter efter behov.