Dokumentaatio

 

Huom: kaikki dokumentit palautetaan .pdf-muodossa!

 

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.

 

Huomaa että jokaisen dokumentin pituus on n. 1-2 A4, poislukien kuvat ja taulukot (todellinen pituus voi olla siis jopa 3-4 sivua).

 

Vaaditut dokumentit:

 

 

Määrittelydokumentti

Mitä algoritmeja ja tietorakenteita toteutat työssäsi

Mitä ongelmaa ratkaiset ja miksi valitsit kyseiset algoritmit/tietorakenteet

Mitä syötteitä ohjelma saa ja miten näitä käytetään

Tavoitteena olevat aika- ja tilavaativuudet (m.m. O-analyysi)

Lähteet

 

Toteutusdokumentti

Ohjelman yleisrakenne

Saavutetut aika- ja tilavaativuudet (m.m. O-analyysi pseudokoodista)

Suorituskyky- ja O-analyysivertailu (mikäli työ vertailupainotteinen)

Työn mahdolliset puutteet ja parannusehdotukset

Lähteet

 

Käyttöohje

Miten ohjelma suoritetaan, miten eri toiminnallisuuksia käytetään

Minkä muotoisia syötteitä ohjelma hyväksyy

Missä kansiossa on jar ja ajamiseen tarvittavat testitiedostot.

 

Testausdokumentti

Mitä on testattu, miten tämä tehtiin

Minkälaisilla syötteillä testaus tehtiin (vertailupainotteisissa töissä tärkätä)

Miten testit voidaan toistaa

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.