Dokumentaatio

Koodin lisäksi tehtävänä on nelja dokumenttia: määrittelydokumentti, toteutusdokumentti, käyttöohje ja testausdokumentti. Dokumenttien merkitys kurssilla on kuitenkin vähäinen: olennainen asia on toimiva ja tehokas koodi! Työn tekemisessä ja arvostelussa painotetaan laitoksen muita harjoitustöitä vähemmän dokumentointia. Ohjelmakoodin on kuitenkin oltava mahdollisimman selkeää, metodien on oltava lyhyitä, luokkien, muuttujien ja metodien on oltava kuvaavasti nimettyjä ja ohjelman rakenteen muutenkin kaikin puolin selkeä.  

Koodin tulee olla kirjoitettu mahdollisimman selkeästi ja ymmärrettävästi. Kommentoi koodiasi kattavasti, mutta napakasti. Jokainen luokka, metodi ja artribuutti ei välttämättä kaipaa kommenttia, mutta kaikki olennainen ja vähemmän kuin itsestään selvä on oltava selostettu kommenteissa. Sisällytä metodien kommentteihin niiden parametrien ja paluuarvon merkitykset. Metodien sisäinen kommentointi ei ideaalitapauksessa pitäisi olla tarpeen, sillä metodien tulee olla kuvaavasti nimettyjä, kompakteja ja yksinkertaisia, helposti hahmotettavia kokonaisuuksia. Mikäli metodin toimintaa kuitenkin on vaikea hahmottaa pelkän koodin ja metodin yleiskommentin perusteella, voidaan sen koodia kommentoida sisäisestikin.

JavaDoc-kommentointia käytetään kaikissa töissä, jotka toteutetaan Javalla. NetBeans toteuttaa pyydettäessä luokille ja metodeille JavaDoc-kommenttien pohjat. Mikäli teet työsi jollakin muulla kielellä, sovi käytetystä kommentoitityylistä ohjaajan kanssa jo alkutapaamisessa. Luokkakaaviot saat lisättyä JavaDoc:iisi suoraan käyttämällä YWorks-nimistä työkalua, joka generoi suoraan NetBeans-projektista kaaviot.

Vaaditut dokumentit:

Määrittelydokumentti

1. Mitä algoritmeja ja tietorakenteita toteutat työssäsi
2. Mitä ongelmaa ratkaiset ja miksi valitsit kyseiset algoritmit/tietorakenteet
3. Mitä syötteitä ohjelma saa ja miten näitä käytetään
4. Tavoitteena olevat aika- ja tilavaativuudet (m.m. O-analyysi)
5. Lähteet

Toteutusdokumentti

1. Ohjelman yleisrakenne
2. Saavutetut aika- ja tilavaativuudet (m.m. O-analyysi pseudokoodista)
3. Suorituskyky- ja O-analyysivertailu (mikäli työ vertailupainotteinen)
4. Työn mahdolliset puutteet ja parannusehdotukset
5. Lähteet

Käyttöohje

1. Miten ohjelma suoritetaan, miten eri toiminnallisuuksia käytetään
2. Minkä muotoisia syötteitä ohjelma hyväksyy
3. Missä kansiossa on jar ja ajamiseen tarvittavat testitiedostot.

Testausdokumentti

1. Mitä on testattu, miten tämä tehtiin
2. Minkälaisilla syötteillä testaus tehtiin (vertailupainotteisissa töissä tärkätä)
3. Miten testit voidaan toistaa
4. Ohjelman toiminnan empiirisen testauksen tulosten esittäminen graafisessa muodossa.

Testaus on ideaalitapauksessa suoritettava ohjelma. Tällöin testi on helposti toistettavissa, mikä helpottaa toteutuksen tekoa jo varhaisessa vaiheessa. On erittäin suositeltavaa käyttää testaukseen JUnitia.