Dokumentaatio

 

Ohjelman lisäksi kurssilla tehdään neljä dokumenttia:

Jokaisen dokumentin pituus on n. 1-2 A4, poislukien kuvat ja taulukot (todellinen pituus voi olla siis jopa 3-4 sivua). Dokumentaatio sijoitetaan kansioon nimeltä "dokumentit", jonka tulee sijaita projektin juuressa.

 

Dokumenttien sisällöstä tarkemmin:

 

• 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

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

• 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
•  

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

 

Javadoc-kommentoinnista

JavaDoc-kommentointia käytetään kaikissa töissä, jotka toteutetaan Javalla. NetBeans generoi automaattisesti 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. Luokkakaavioita ei kuitenkaan vaadita.

Muista pitää kommentointi ajantasalla, kun muutat tai kehität ohjelmaasi!

 

 

Ohjelmointityylistä

Ohjelmakoodin on 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. Sisällytä metodien kommentteihin niiden parametrien ja paluuarvon merkitykset. Muista kommentoida myös luokkia.

 

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.

 

Lopuksi

Työn tekemisessä ja arvostelussa painotetaan laitoksen muita harjoitustöitä vähemmän dokumentointia, mutta parhaimpiin arvosanoihin ei voi yltää, jos dokumentointi on selvästi puutteellista.