Dokumentointi-Bitwise-blog

Erilaisissa projekteissa tulee poikkeuksetta vastaan tilanne, jossa projektin aikana opittuja asioita pitäisi dokumentoida. Dokumentti voi olla tarkoitettu itselle muistiinpanoksi (”näin aloitat uuden kirjaston tekemisen”), projektin muille/tuleville jäsenille hyödyksi (”kannattaa käyttää tässä kirjastoa X tai muuta vastaavaa”) tai tiedoksi jopa laajemmalle joukolle (”kun olet rakentamassa palvelua A, muista ottaa huomioon nämä asiat”). Dokumentaatio voi koskea projektin yleisiä käytäntöjä tai sitten esimerkiksi tuotettua koodia. Yleensä tässä vaiheessa avataan tekstinkäsittelyohjelma ja aloitetaan naputtelu tietojen siirtämiseksi aivoilta digitaaliseen muotoon. Joillekin projekteille on voitu pystyttää dokumentointia varten wiki-sivusto, jonne tietojen siirtäminen käy vastaavalla tavalla, mutta tietojen löytäminen on myöhemmin mahdollisesti hiukan helpompaa.

Pohdimme eräänä päivänä kaveripiirissä sitä, miksi olisi tärkeää opettaa muiden opintojen ohessa ihmisille suunnittelumalleja (engl. design patterns) ja malliajatusta ylipäätänsä. Tongittuamme tarpeeksi asiaa päädyimme suunnittelumallien perimmäiseen ideaan: suunnittelumallit ovat määrätyssä formaatissa olevia dokumentteja yleisestä tietämyksestä tiettyyn asiaan liittyen. Ja kannattaa huomata, että formaatti tässä tapauksessa ei tarkoita lähinnä koneluettavaa XML:ää, vaan enemmänkin ihmisluettavaa proosaa.

Kun malliajatuksen ”luoja” C. Alexander kumppaneineen mietti rakennusarkkitehtuurin syntyjä syviä, tarkoitus oli dokumentoida ajattomia, usein myös kirjoittamattomia sääntöjä alan hyville käytännöille. Alexander määritteli suunnittelumallin näin: ”A pattern is at the same time a thing, which happens in the world, and the rule which tells us how to create that thing, and when we must create it”. Tärkeää on tässä kohden huomata, että vaikka suunnittelumalli on kuvaus asiasta, joka on jo olemassa, se on samalla myös kuvaus prosessista, jolla voimme luoda tämän asian.

Valitettavan usein suunnittelumallit ovat monelle pelkkä synonyymi Gang of Fourin Design Patterns -kirjassa esitellyille ratkaisuille. Valitettavasti siinä mielessä, että pahimmat mallipuristit eivät pidä kirjaa edes alan julkaisuna, vaan lähinnä eri ohjelmointikielten heikkouksia paikkaavana niksipirkkana – kirjan tekijöiden kiivaista vastaväitteistä huolimatta. Tilannetta ei yhtään helpota se tosiseikka, että sana ”pattern” on eräs ylikuormitetuimmista termeistä, jolloin sinänsä samoilla sanoilla keskustelevat ihmiset puhuvat täysin eri asioista, eivätkä siten välttämättä ymmärrä toisiaan. Suomeksi tilanne ei ole yhtään sen helpompi.

Kun seuraamme Christopherin jalanjälkiä, voimme käyttää suunnittelumalleja dokumentoimaan lähes minkä tahansa alueen yleistä tietämystä. Näinhän on tehtykin. Arkkitehtuurialan lisäksi on dokumentoitu myös suunnittelumallien kirjoitusta ja työstämistä, sulautettujen järjestelmien ohjelmistojen erityispiirteitä, koneenohjausjärjestelmiä, turvakriittisiä ohjelmistoja, startup-yritysten perustamista, toimivia yritysorganisaatioita, vieraiden kielten opetusta… Lista on suorastaan loputon. Miksi emme siis käyttäisi malleja myös projektissa kertyneen tietämyksen ja ohjelmiston dokumentointiin? Lisävinkkejä asiasta antavat esimerkiksi Odenthal ja Harrison. Toki on mahdollista käyttää olemassa olevia suunnittelumalleja tuottamaan perinteisen muotoista dokumentaatiota (esimerkiksi Rüping ja Avgeriou).

Wiki-sivut ja tekstinkäsittelydokumentit eivät suinkaan ole vastakohta suunnittelumalleille. Suunnittelumallien hienoin idea on se, että noudattaen jotain suunnittelumallien yleisistä formaateista (katso esimerkiksi Pattern Forms), tulee automaattisesti vastanneeksi kolmeen tärkeimpään kysymykseen: Mitä? Miksi? Milloin? Kuinka moni voi sanoa samaa omasta projektin wiki-sivustaan tai muusta dokumentaatiostaan?

Seuraavassa osassa käymme läpi esimerkin siitä, kuinka projektin käytäntöjä kuvaava yksinkertainen suunnittelumalli luodaan.