- TIE-0240x
- 14. Ohjelman dokumentointi
- 14.1 Ohjelman dokumentointi
Ohjelman dokumentointi¶
Ohjelman dokumentaatio voi olla erillinen ohjelmakoodin mukana tuleva tai ohjelmakoodissa itsessään oleva kuvaus siitä, miten ohjelma toimii, miten se on toteutettu ja miten sitä tulisi käyttää. Ohjelman kehittäjille dokumentaatiosta tulisi käydä ilmi vähintään seuraavat asiat:
- Ohjelman toiminnalliset vaatimukset eli spesifikaatio
- Ohjelman kokonaisarkkitehtuuri
- Koodin dokumentointi: rajapinnat, kooditason kommentit
- Toteutushistoria: versionhallinnan loki
- Käyttöohje
- ...
Dokumentaatiolla on aina kohderyhmä. Dokumentit voivat olla projektin sisäisiä tai tarkoitettu projektin ulkopuolisille. Hyvä dokumentaatio huomioi kohderyhmän ja samalla on kohderyhmästä riippumatta:
- selkeä
- lyhyt
- kattava
- sisältää kaiken tarpeellisen tiedon
- ei sisällä mitään turhaa
Toimiva ohjelmisto ohittaa kattavan dokumentaation¶
Ketterässä ohjelmistokehityksessä agile manifestosta alkaen korostaa ohjelmiston tärkeyttä dokumentaation kustannuksella. Tämä ei kuitenkaan tarkoita sitä, että dokumentointi olisi turhaa. Painotus kuitenkin on, että dokumentoidaan vain eri sidosryhmien kannalta olennaiset asiat ja unohdetaan dokumentointi dokumentoinnin vuoksi.
Ohjelmistoprojektin dokumentaatio koostuu usein joukosta erilaisia datalähteitä. Dokumentaatioksi lasketaan esim.:
- luokkakaavio
- README
- Muutosloki
- Rajapintadokumentaatio
- Versionhallinan lokit
- Käyttöohje
Harjoitustyön dokumentaatio¶
Harjoitustyön dokumentaatiossa kohderyhmänä on tiimi itse, työn arvosteleva kurssihenkilökunta sekä työn vertaisarvioiva ryhmä. Jokaisessa harjoitustyössä on siis oltava versionhallinnassa hakemisto Documentation
, jossa ajantasainen dokumentaatio ohjelmasta sijaitsee. Dokumentaatio kokonaisuutena koostuu seuraavista:
- Versionhallinnan lokit
- Koodin kommentit, ml. mahdollinen omien luokkien rajapintadokumentaatiot
- PDF-dokumentti
Documentation
-hakemistossa
Dokumentissa kuvataan:
- ryhmän toteuttaman ohjelman osan rakenne. Selkeä paperille käsin piirretty kaavio käy oikein hyvin.
- tärkeimpien luokkien vastuujako
- ohjelman toiminta eli miten harjoitustyön oliot yhdessä toteuttavat ohjelman
- ne ryhmän toteuttamat luokat, joissa on dokumentoituna esi- ja jälkiehtoja yms.
- jokainen vapaaehtoinen ominaisuus selkeästi kuvattuna
- sovittu ja toteutunut työnjako
- lyhyt käyttöohje ml. pelin kuvaus eli millaiset säännöt pelillä on
- tiedossa olevat ongelmat tai puutteet
Huomatkaa erityisesti, että on dokumentaation tarkoitus antaa vertaisarvioinnin tekevälle ryhmälle yleiskuvaus harjoitustyön toteutuksesta, jotta he pystyvät vertaamaan toteutusta omaan toteutukseensa.
PDF-dokumentin tulee olla enintään viisi (5) sivua pitkä.