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ä.