Yksi varoitus: Eri tiimeillä on erilaiset standardit ja konventiot teknistä suunnittelua varten. Suunnitteluprosessille ei ole olemassa alan laajuista standardia, eikä voisikaan olla, sillä eri kehitystiimeillä on erilaisia tarpeita tilanteesta riippuen. Se, mitä kuvaan, on yksi mahdollinen vastaus, joka perustuu omaan kokemukseeni.

Aloitetaan perusasioista: Mikä on tekninen suunnitteluasiakirja ja miten se sopii suunnitteluprosessiin?

Teknisessä suunnitteluasiakirjassa kuvataan ratkaisu tiettyyn tekniseen ongelmaan. Se on spesifikaatio eli ”suunnittelupiirustus” ohjelmisto-ohjelmalle tai -ominaisuudelle.

TDD:n ensisijainen tehtävä on välittää tiimin jäsenille tehtävän työn tekniset yksityiskohdat. On kuitenkin olemassa toinenkin tarkoitus, joka on yhtä tärkeä: TDD:n kirjoittamisprosessi pakottaa sinut järjestämään ajatuksesi ja pohtimaan suunnittelun jokaista osa-aluetta varmistaen, ettet ole jättänyt mitään pois.

Tekniset suunnitteludokumentit ovat usein osa laajempaa prosessia, jossa on tyypillisesti seuraavat vaiheet:

1. Tuotevaatimukset määritellään. Näitä edustaa tyypillisesti tuotevaatimusasiakirja (PRD, Product Requirements Document). PRD:ssä määritellään, mitä järjestelmän on tehtävä käyttäjän tai ulkopuolisen toimijan näkökulmasta.
2. Tekniset vaatimukset määritellään. Tuotevaatimukset muunnetaan teknisiksi vaatimuksiksi – mitä järjestelmän on saavutettava, mutta nyt miten se tekee sen. Tämän vaiheen tuloksena syntyy teknisten vaatimusten asiakirja (Technical Requirements Document, TRD).
3. Tekninen suunnittelu. Tämä sisältää teknisen kuvauksen ratkaisusta edellisissä vaiheissa hahmoteltuihin vaatimuksiin. TDD on tämän vaiheen tuotos.
4. Toteutus. Tässä vaiheessa ratkaisu todella rakennetaan.
5. Testaus. Järjestelmä testataan PRD:tä ja TRD:tä vasten sen varmistamiseksi, että se todella täyttää määritellyt vaatimukset.

Kaikkien näiden vaiheiden välillä on tyypillisesti tarkistusprosessi, jolla varmistetaan, ettei virheitä ole tehty. Jos virheitä, väärinkäsityksiä tai epäselvyyksiä havaitaan, ne on korjattava ennen seuraavaan vaiheeseen siirtymistä.

Tämä prosessi on hyvin vaihteleva; tässä luetellut vaiheet muuttuvat tapauskohtaisesti. Esimerkiksi:

• Pienemmissä ominaisuuksissa, joihin ei liity paljon monimutkaisuutta, vaiheet 2 ja 3 yhdistetään usein yhdeksi asiakirjaksi.
• Jos ominaisuuteen liittyy paljon tuntemattomia tekijöitä tai jonkinasteista tutkimusta, voi olla tarpeen rakentaa proof-of-concept-toteutus ennen teknisen suunnittelun viimeistelyä.

Tämä prosessi tapahtuu myös eri mittakaavoissa ja eri rakeisuustasoilla. PRD / TRD / TDD voi koskea koko järjestelmän suunnittelua tai vain yksittäistä ominaisuutta. Useimmissa ympäristöissä prosessi on myös syklinen – jokainen suunnittelu-/toteutussykli perustuu edellisen syklin työhön.

Raja TRD:n ja TDD:n välillä voi toisinaan olla hieman häilyvä. Oletetaan esimerkiksi, että kehität palvelinta, joka kommunikoi RESTful API:n kautta. Jos tavoitteena on noudattaa jo vakiintunutta ja dokumentoitua API:ta, API-spesifikaatio on osa vaatimuksia ja siihen tulisi viitata TRD:ssä. Jos taas tavoitteena on kehittää täysin uusi API, API-spesifikaatio on osa suunnittelua, ja se olisi kuvattava TDD:ssä. (Vaatimusasiakirjassa on kuitenkin edelleen määriteltävä, mitä API:lla yritetään saavuttaa.)

TDD:n kirjoittaminen

Tänä päivänä on yleinen käytäntö kirjoittaa teknisiä dokumentteja yhteistoiminnallisessa dokumenttijärjestelmässä, kuten Google Docsissa tai Confluencessa; tämä ei kuitenkaan ole ehdoton vaatimus. Tärkeää on, että tiimisi jäsenillä on mahdollisuus kommentoida asiakirjaa ja huomauttaa virheistä ja puutteista.

Useimmat TDD:t ovat yhdestä kymmeneen sivua. Vaikka TDD:n pituudelle ei ole ylärajaa, hyvin laajoja asiakirjoja on sekä vaikea muokata että lukijoiden on vaikea omaksua; harkitse asiakirjan jakamista erillisiin asiakirjoihin, jotka kuvaavat toteutuksen yksittäisiä vaiheita tai vaiheita.

Diagrammeista on hyötyä; on olemassa useita online-työkaluja, joita voit käyttää kuvien upottamiseen asiakirjaan, kuten draw.io tai Lucidchart. Voit myös käyttää offline-työkaluja, kuten Inkscapea, SVG-kaavioiden luomiseen.

Dokumentin tulisi olla perusteellinen; ideaalitapauksessa jonkun muun kuin TDD:n laatijan tulisi olla mahdollista toteuttaa suunnitelma kirjoitettuna. Jos esimerkiksi suunnittelussa määritellään API:n toteutus, jokainen API-päätepiste tulisi dokumentoida. Jos suunnittelussa on hienovaraisia valintoja, ne tulisi mainita.

Välttää yleisiä kirjoitusvirheitä

Vähemmänkin yleinen virhe, johon törmään TDD:ssä, on kontekstin puute. Toisin sanoen kirjoittaja kirjoittaa mahdollisimman vähin sanoin, miten hän ratkaisi ongelman; mutta hän ei sisällytä mitään tietoa siitä, mikä ongelma oli, miksi se piti ratkaista tai mitä seurauksia kyseisen ratkaisun valitsemisella oli.

On myös tärkeää pitää mielessä, kuka todennäköinen lukija on ja millä tasolla hänen ymmärryksensä on. Jos käytät termiä, jota lukija ei ehkä tunne, älä pelkää lisätä sille määritelmää.

Tuskin tarvitsee mainita, että hyvä kielioppi ja oikeinkirjoitus ovat avuksi. Vältä myös kiusausta sanaleikkeihin tai ”nokkelaan” oikeinkirjoitukseen; vaikka ohjelmoijilla on tapana pitää kielellä leikkimisestä, olen nähnyt useamman kuin yhden tapauksen, jossa liiallinen kevytmielisyys on päätynyt maksamaan tiimille turhaa vaivaa väärinkäsitysten vuoksi. On ihan oikein käyttää satunnaisesti huumoria tai valita ominaisuuksille ja järjestelmille värikkäitä, mieleenpainuvia nimiä, koska se auttaa ihmisiä muistamaan ne. Mutta älä anna halusi näyttää, kuinka nokkela olet, muuttua häiriötekijäksi.

Nimistä puheen ollen, valitse ne huolellisesti; kuten Mark Twain kerran kirjoitti: ”Valitse oikea sana, älä sen pikkuserkku.” Insinööreillä, joilla on huono sanavarasto, on taipumus käyttää samoja yleisiä termejä yhä uudelleen eri asioista, mikä johtaa ylikuormitukseen ja sekaannukseen. Esimerkiksi luokan nimeäminen ”DataManager” on epämääräistä eikä kerro mitään siitä, mitä se oikeastaan tekee; samaan tapaan paketti tai hakemisto nimeltä ”utils” voi sisältää käytännössä mitä tahansa. Konsultoi tesaurusta, jos haluat löytää paremman sanan, tai paremminkin erikoistuneesta synonyymitietokannasta, kuten WordNetistä.

TDD-malli

Kirjoittaessasi TDD:tä voi olla hyödyllistä aloittaa vakiomallin avulla. Seuraavassa on malli, jota olen käyttänyt useissa projekteissa. Huomaa, että tätä mallia tulisi muokata tarpeen mukaan; voit vapaasti poistaa kohtia, jotka eivät sovellu, lisätä uusia kohtia tai nimetä otsikoita uudelleen tarpeen mukaan.