Pragmaattista arkki­tehtuuria dokumen­toimassa

Oct 31, 2014, 10:14 PM

Ketterä kehittäminen on saavuttanut jo ainakin jollain tasolla jokaisen ohjelmistokehittäjän ja tiimin. Toimivaa ohjelmaa arvostetaan ohi teorioiden ja dokumentaation. Tuotantoon halutaan mahdollisimman pian, sillä tiedetään, että vasta loppukäyttäjiltä saatu palaute antaa oikeita vihjeitä tuotteen tai ohjelmiston onnistumisesta.

Perinteisellä vesiputousmalliin vahvasti liitetyllä arkkitehtuurisuunnittelulla on huono maine. Se on perinteisesti tuottanut suuren määrän dokumentaatiota. Kun ohjelmiston kehitys on aloitettu, suuri osa tästä arkkitehtuuridokumentaatiosta on havaittu virheelliseksi tai tarpeettomaksi. Hyödylliseksi koettu osa on ollut työlästä pitää ajan tasalla. Kun uusi kehittäjä saapuu tiimiin, myös tämä dokumentaatio on usein auttamattomasti vanhentunutta.

Lean ja tasapaino

Verkkokauppa Amazon löytää katalogistaan tuhansia ja taas tuhansia kirjoja ohjelmistoarkkitehtuurit-aihealueelta. Lukemani perusteella tiedän näiden kirjojen sisältävän paljon arvokasta tietoa, osaamista ja ymmärrystä. Moni ketterä projekti jättää kuitenkin arkkitehtuurisuunnittelun ja liiketoimintaan tutustumisen tekemättä lähes kokonaan. Tämä on voimakas vastareaktio liialliselle etukäteen suunnittelemiselle, ja ketterien toimintatapojen on katsottu oikeuttavan tämän. Kuitenkin jopa test driven development -ajattelun sanansaattajana tunnettu Robert “Uncle Bob” Martin myöntää suoraan, että “arkkitehtuurin syntyminen pelkästään testien pohjalta on hölynpölyä”.

Lean-ajattelu suosittelee riittävää etukäteen suunnittelua, jos sillä voidaan säästää turhaa työtä myöhemmin. “Balancing Agility and Discipline” -kirjassa on koostettu kokemuksia ja tuloksia suuresta määrästä eri tavoin toteutettuja ohjelmistoprojekteja. Näistä vertailtiin etukäteen tehdyn arkkitehtuurisuunnittelun työmäärän suhdetta koko projektin kustannuksiin. Ei ole yllättävää, että paras suhde näille löytyy graafin keskikohdilta: riittävällä etukäteen suunnittelulla vältettiin suuria uudelleen kirjoittamisia projektin myöhemmässä vaiheessa, ja toisaalta turhaa dokumentaatiota ennen toteutuksen tarjoamaa oletusten validointia.

Käsitteet selviksi

Olio-ohjelmointi syntyi ajatukselle, että ohjelmoijat voivat suoraan toteuttaa koodilla mallit, joita heillä ongelman käsitelyssä syntyi omassa päässään. Olio-ohjelmointi levisi nopeasti myös käyttöliittymien toteuttamiseen. Kun käyttöliittymä esitti asiat olioina – jotka täsmäsivät käsitteisiin ja rakenteisiin, joilla käyttäjät päässään tilanteen mallinsivat – koettiin käyttöliittymä intuitiiviseksi.

Varmin tapa tehdä huonoksi koettu sovellus on siis tilanne, jossa sovelluksen tekijä puhuu eri käsitteillä kuin loppukäyttäjä tai ohjelmoija tarkoittaa käsitteellä eri asiaa kuin loppukäyttäjä.

Domain-mallinnus eli käsitteiden nimeäminen, selittäminen ja näiden suhteiden toisiinsa selvittäminen on mielestäni yksi tärkeimmistä arkkitehtuurisuunnittelun etukäteen tehtävistä toimista. Mallinnuksella on mahdollista välttää suuria väärinymmärryksiä ja niistä seuraavia uudelleen kirjoittamisia myöhemmin projektissa. Pyri siis siihen, että ketterä tiimisi puhuu samaa kieltä bisneksen ja loppukäyttäjän kanssa – ja mitä aiemmin sen parempi. Jos olet järjestelmää suunnitteleva arkkitehti etkä ole koskaan tavannut järjestelmän loppukäyttäjiä, toivon sinua häpeävän. Mene paikan päälle – Genchi Genbutsu (現地現物)!

Kenelle dokumentoit?

Vanhoissa arkkitehtuurikehyksissä tuotettava dokumenttiluettelo on mittava ja dokumenttien sisältö harvoin lyhyt ja ytimekäs. Useassa organisaatiossa näiden dokumenttien tuottamista helpotetaan valmiilla dokumenttipohjilla. Valmiista pohjista seuraa kuitenkin useammin paljon turhaa tekstiä kuin hyvin mietittyjä dokumentteja: “Ai tässä on tämmöinen luku.. No, siihen varmaan pitäisi kirjoittaa jotain.”

Kun aloitat uutta dokumenttia, tärkeintä on aina esittää kysymys: kenelle tämä dokumentti on tarkoitettu? Kuka sen lukija on? Jos vastausta on vaikea löytää, kannattaa dokumentti jättää kirjoittamatta. Kun lukija on tiedossa, tulee dokumentti kirjoittaa hänelle. Muotoile teksti ja dokumentin rakenne niin, että se palvelee juuri tätä lukijaa. Jätä surutta tieto kirjoittamatta, jos sillä ei ole arvoa odotetulle lukijalle.

Ketterää dokumentointia

Ketterän ohjelmistoprojektin edetessä ohjelmiston koodi on ainoa varmasti ajan tasalla oleva asia. Jotta samaa tietoa ei tarvitse pitää yllä monessa paikassa, tulisi koodikannan olla suoraan tiedonlähteenä aina kun mahdollista. Tämä voi tarkoittaa suoraan kooditiedostoon liitettävää metatietoa tai koodista dynaamisesti generoitavaa informaatiota. Esimerkiksi Java-kielellä rajapinnan käyttöohjeet voidaan kirjoittaa Javadocceina ja aina ajantasainen UML-domainmalli voidaan rakentaa esimerkiksi kirjoittamallani reflektiota ja GraphViz-kirjastoa käyttävällä Domain Reverse Mapper -sovelluksella, https://github.com/NitorCreations/DomainReverseMapper.

Muihin ylläpidettäviin dokumentteihin kannattaa keskittyä dokumentoimaan asioita, joiden selvittäminen koodista suoraan on vaikeaa. Yksinkertainen komponentti- ja integraatiokaavio helpottaa projektin hahmottamista. Näiden ylläpito onnistuu helpoiten esimerkiksi PlantUML:n työkalulla, joka muuntaa yksinkertaisen tekstitiedoston sisältämän kuvauksen UML-graafiksi. Tässä muodossa tiedosto on myös helppo tallentaa versionhallintaan koko tiimin päivitettäväksi.

Viimeisenä vaihtoehtona on perinteinen dokumentti. Moni hyödyllinen dokumentti on ainoastaan sivun tai parin pituinen ja tällaisen voi hyvin sijoittaa esimerkiksi wikiin ylläpidettäväksi. Näistä esimerkkinä voi antaa jo aikaisemmin mainitun domain-sanaston (ubiquitous language) ja arkkitehtuuripäätöslokin, josta on helppo tarkistaa tehdyt päätökset ja niiden perusteet, jotta samoja ongelmia ei tarvitse ratkoa useaan kertaan.

Lopuksi

Ketterän kehityksen ei tarvitse – eikä mielestäni pidä – tarkoittaa arkkitehtuurin kuolemaa. Pragmaattinen arkkitehtuuri ketterässä projektissa vaatii kyllä muutoksia monen organisaation totuttuihin dokumentointitapoihin. Joka dokumentilla tulee olla oikea yleisö ja tarve. Dokumenttien ylläpidon tulee olla automaattista tai hyvin helppoa, ja ne kannattaa työstää yhdessä asiakkaan kanssa. Näin vältytään paljolta turhalta työltä ja monilta väärinymmärryksiltä.

Menestystä seuraavaan projektiisi!

Kirjoittajasta

Janne Sinivirta on ohjelmistoarkkitehti, seminaaripuhuja, valokuvaaja, urheiluintoilija ja kahden lapsen ylpeä isä. Hän tekee töitä Nitorille ja on kirjoittanut koodia työkseen 17 vuotta.