Toteutusdokumentti

Tämä on yleinen dokumentointiohje - kaikki ei välttämättä sovellu juuri sinun aiheeseesi. Käytä järkeäsi! Pyri helposti ymmärrettävään ja selkeään ilmaisuun sekä ulkoasun että kielen osalta. Ole täsmällinen ja kirjoita tiiviisti.

Toteutusdokumentissa tulee olla seuraavat osat:

1. kansilehti
2. sisällysluettelo
3. käyttöohje
4. ohjelman toiminta- ja rakennekuvaus
5. testauksen kuvaus
6. liitteet

Varsinainen dokumentti alkaa sisällysluettelon jälkeen: sivujen numerointi alkaa käyttöohjeesta. Numeroi myös otsikot, kuvat ja kaaviot. Kuvat ja kaaviot tulee myös nimetä ja niihin on viitattava tekstissä.

Kansilehti

Kansilehteen tulee seuraavat tiedot:

• tehtävän nimi,
• käytetty ohjelmointikieli,
• tekijän nimi ja yhteystiedot,
• oppilaitos,
• kurssin nimi,
• ohjaaja ja
• päiväys.

Esimerkki kansilehden asettelusta.

Sisällysluettelo

Sisällysluettelossa luetellaan dokumentin numeroidut luvut ja kappaleet sivunumeroineen. Sisällyksen jälkeen luetellaan mukana seuraavat liitteet. Otsikoksi "Sisällys" tai "Sisältö", ei sivunumeroita.

Käyttöohje

Käyttöohje suunnataan tavalliselle ohejlman käyttäjälle, jolla oletetaan olevan perustiedot tietokoneiden käytöstä. Käyttöohjeessa kerrotaan mihin ja miten ohjelmaa käytetään. Sen tulisi toisaalta opettaa lukija käyttämään ohjelmaa mutta myös vastata käytön aikana eteen tuleviin ongelmiin ja virhetilanteisiin. Mieti, mitä lukija sisällysluettelosta etsii.

Käyttöohjeen tulee jäsentelyltään mukailla ohjelman käyttötapaa. Etenkin vuorovaikutteisessa ja valikko-ohjatuissa ohjelmissa on järkevintä esittää toiminnot syötteineen ja tulosteineen niiden luontevassa esiintymisjärjestyksessä.

Huom! Aikaisemmin tehty määrittelydokumentti muistuttaa jonkin verran käyttöohjetta. Tästä syystä on aivan sallittua kopioida joitakin osia määrittelydokumentista käyttöohjeeseen - edellyttäen toki että lopullinen ohjelma vastaa edelleen määrittelyään.

Seuraavia asioita olisi hyvä sisällyttää käyttöohjeeseen:

Ajo-ohje: Ohjeet ohjelman asentamiseen. Kuinka ohjelma käynnistetään ja mitä parametreja sille voi antaa? Listaa kaikki ajamiseen tarvittavat tiedostot.

Lyhyt esittely ohjelmasta: Kerro mitä ohjelma tekee ja mihin sitä voi käyttää.

Laitteistovaatimukset: Mitä vaatimuksia ohjelma asettaa laitteistolle käyttöjärjestelmän tms. suhteen. Kerro ainakin millä laitteistolla ja millä javan versiolla ohjelmaa on testattu. Applettia tehdessä voi myös mainita millä selaimilla ohjelmaa on kokeiltu.

Peli-idea: Jos teet peli-ohjelman, kerro myös mistä pelissä on kyse ja kuinka sitä pelataan.

Ohjelman toiminnot: Kuvaus kaikista ohjelman toiminnoista. Esimerkiksi valikkopohjaisissa ohjelmissa kuvaus kaikista valikkojen ja alivalikkojen toiminnoista omassa (ali)luvussaan. Tämän voi kirjoittaa määrittelydokumentin käyttötapausten mukaisesti.

Syöttötiedot: Mitä syötteitä annetaan ja miten? Missä muodossa syötteiden tulee olla. Syötteiden rajoitukset.

Tulostetiedot: Mitä ohjelma tulostaa ja milloin? Miten tulokset on laskettu? Näytön vakiotekstit eivät ole tulosteita.

Ohjelman rajoitukset: Esimerkiksi: Asiakkaita voi olla korkeintaan 50.

Virheilmoitukset: Kuvaus siitä, miten virhetilanteissa pitäisi toimia. Kerro jokaisesta virheestä mikä sen aiheutti ja missä tilanteessa, virheilmoitus ja toiminta jatkossa. Taulukko on kätevä tapa dokumentoida virheilmoitukset (Kuva 1).

Ohjelman toiminta ja rakenne

Ohjelman toteutuksen kuvaus on tarkoitettu toiselle ohjelmoijalle, joka haluaa tutustua ohjelman toimintaan ehkä täydentääkseen tai korjatakseen sitä (tai puhtaasta mielenkiinnosta). Siitä tulee käydä ilmi ratkaisuperiaatteet, tietorakenteet ja toiminnan pääpiirteet.

Toiminta- ja rakennekuvaus on eräänlainen ohjelmoijan käyttöohje: näin käytät luokkiani. Luokkien kuvaksen tulisi toimia samalla tavalla kuin Javan API-kuvaus, eli dokumentin lukijan täytyy pystyä käyttämään luokkia tutustumatta lähdekoodiin. Javan API-kuvaksesta poiketen harjoitustyön yhteydessä dokumentoidaan myös private-tyyppiset muuttujat ja metodit.

Seuraavassa toiminnan ja rakenteen kuvauksessa käsiteltävät asiat.

Yleiskuvaus

Lyhyt esittely ohjelman toteutuksesta ohjelmoijan näkökulmasta. Kerro ohjelman rakenteesta ja perustele valittuja ratkaisuja. Kuvaa lisäksi ohjelman tärkeimmät algoritmit ja niiden toiminta. Tarvittaessa voi käyttää pseudokoodia. Yleiskuvaus tulee kirjoittaa niin, että siitä saa nopeasti pääpirteittäisen kuvan ohjelman toteutuksesta.

Luokkarakenne

Dokumenttiin tulee luokkakaavio, jossa on esitetty kaikki ohjelmassa olevat luokat ja niiden väliset suhteet. Luokkakaavion yhteydessä kuvataan sanallisesti myös jokaisen luokan tehtävä kokonaisuuden kannalta sekä luokkien väliset yhteydet.

Jos luokkakaaviosta/-hierarkiasta tulee iso, se kannattaa jakaa pienempiin osiin ja/tai sijoittaa liitteeksi.

Huom! Luokkarakenne on sama kuin suunnitteluvaiheessakin. Mikäli luokkarakenne on säilynyt ohjelmointivaiheen läpi samanlaisena, niin riittää että kopioit tämän osion suunnitelmastasi. Käytännössä kuitenkin muutoksia aina tulee ohjelmointivaiheessa, jotka sinun pitäisi päivittää tähän luokkarakenteeseen.

Luokkien kuvaus

Kirjoita jokaisesta luokasta yleiskuvaus, jossa kerrotaan mitä luokka kuvaa ja mihin sitä käytetään. Kerro myös luokan yliluokka ja sen toteuttamat rajapinnat.

Kuvaa luokan tietorakenteet. Esittele kaikki luokan muuttujat ja kuvaa ne. Kirjoita tarkempi kuvaus luokan tärkeimpien tietorakenteiden käytöstä.

Dokumentoi kaikki luokan metodit. Kerro metodin tehtävä, sen mahdolliset sivuvaikutukset (esimerkiksi luokan tietorakenteisiin) ja kuvaa metodin parametrit, paluuarvot ja heittämät poikkeukset. Luokan konstruktorit dokumentoidaan samalla tavalla.

Kirjoita jokaisesta metodista oma kappale, otsikoksi käy hyvin metodin määrittely. Aivan yksinkertaiset arvon palauttavat tai asettavat metodit voi kuvata esimerkiksi taulukossa.

Älä selosta. Tarkoitus ei ole käydä ohjelmakoodia läpi sanallisessa muodossa. Älä myöskään laita varsinaista koodia dokumenttiin. Tarvittaessa voi käyttää pseudokoodia.

Huom! Tämän kappaleen voi korvata laittamalla liitteeksi ohjelman API-kuvauksen. API-kuvauksen tulee olla tavallista laajempi niin, että siinä kuvataan myös yksityiset luokat, muuttujat ja metodit. Tämä onnistuu ajamalla javadoc komennolla:

javadoc -private -author -version <omapakkaus>

missä <omapakkaus> on ohjelmasi sisältävän pakkauksen nimi (tai jos et käyttänyt pakkausta niin *.java).

Lukaise kuitenkin läpi generoitu API-kuvaus ja korjaa mahdolliset puutteet (tuliko kaikki luokat mukaan, onko kaikki kentät ja muuttujat kuvattu?), ennen kuin tulostat sen liitteeksi.

Ohjelman toiminta

Kuvaa ohjelman tärkeimpien käyttötapausten toiminta eli olioiden 'keskustelu' sekvenssikaavioin. Tässäkin riittää että kopioit suunnitteluvaiheessa tehdyt sekvenssikaaviot ja päivität ne lopullista toteutusta vastaavaksi.

Kirjoita myös lyhyt sanallinen kuvaus kustakin sekvenssikaaviosta.

Ohjeet ohjelman rajoitusten poistamiseksi

Lyhyt selostus ohjelman merkittävimmistä rajoituksista ja puutteista ja siitä, miten nämä voitaisiin poistaa.

Parannusehdotuksia

Ehdotuksia siitä, miten ohjelmaa voisi kehittää edelleen.

Testauksen kuvaus

Testiselostuksessa selvitetään, miten on vakuuttauduttu ohjelman oikeasta toiminnasta. Testien pitäisi olla toistettavissa dokumentoinnin perusteella.

Dokumentoi jokainen tekemäsi testi. Kerro mitä testataan, miten (kattavuusmitat, testimenetelmät), mitä tuloksia testin pitäisi antaa ja mitä tuloksia on saatu. Jäsentele testauksen kuvaus tekemiesi testien mukaan: käytä alilukuja ja otsikoi kuvaavasti.

Jokaisesta testitapauksesta dokumentoidaan:

• Testin nimi
• Mitä toimintoa testataan
• Miksi testataan, mitä yritetään testillä saada selville
• Mikä on testin alkutilanne
• Miten testataan, eli mitä testissä tehdään
• Mitä testissä pitäisi tapahtua, mikä on odotettu tulos
• Testin tulos (eli ohjelman reaktio testissä tehtäviin asioihin)

Varsinainen testiaineisto kannattaa sijoittaa liiteeksi ja ainoastaan viitata siihen testauksen kuvauksessa. Testiaineistoa ovat esimerkiksi käytetyt main()-metodit ja tulosteet esimerkkiajoista. Jos testauksessa on käytetty apuna muita luokkia, esimerkiksi testiajureita tai tynkäluokkia, ne on myös kuvattava ja sijoitettava liiteeksi.

Testauksesta dokumentoidaan lopullinen testaus, jossa virheitä ei enää pitäisi löytyä. Jos ohjelmaan jää kuitenkin virheitä, ne on ehdottoman tärkeää dokumentoida. Samoin mahdolliset puutteet testauksessa pitää selvittää.

Liitteet

Liitteet numeroidaan (LIITE 1, LIITE 2, ...) ja niihin merkitään myös oma nimi. Liiteeksi tulee ainakin

• Määrittelydokumentti
• Työn suunnitelma
• API-kuvaus
• Tuntikirjanpitolista
• Testaamiseen käytetyt main()-metodit
• Tulosteet testiajoista
• Luokkakaavio (jos se on iso)
• Sekvenssikaaviot (jos isoja)

Yleensä ottaen kaikki, mikä tekee dokumentin lukemisesta hankalaa, kannataa laittaa litteeksi.