Projekti: dokumentaatio¶

Esi- ja jälkiehdot

Dokumentaatio-ohjeista on poistettu vaatimus dokumentoida “Ne ryhmän toteuttamat luokat, joissa on dokumentoituna esi- ja jälkiehtoja yms.”. Esi- ja jälkiehtojen dokumentointi oli relevanttia harjoitustyön edellisessä versiossa, mutta ei niinkään nykyisessä versiossa eli sääsovelluksessa. Huomaa, että ehtojen dokumentointi tekee dokumentista vain paremman. Näin jo tehtyä ehtojen dokumentaatiota ei ole tarpeen poistaa.

Tekoälyn käytöstä

Ohjeisiin on päivitetty vaatimus dokumentoida mahdollinen tekoälyn käyttö projektityössä. Asia kerrottiin tehtävänannossa, mutta ei erikseen tässä luvussa. Aiemman lisäksi on mainittu, että toivomme myös ajatuksiasi tekoälyn hyödyistä ja haitoista projektityössä.

Projekti kuuluu dokumentoidan osana tehtyä työtä. Projektin dokumentaatiossa kohderyhmänä on tiimi itse sekä työn arvosteleva kurssihenkilökunta. Jokaisessa harjoitustyöprojektissa on oltava hakemisto Documentation, jossa ajantasainen dokumentaatio ohjelmasta sijaitsee.

Projektin arvosteltava dokumentaatio kokonaisuudessaan sisältää:

PDF-dokumentin Documentation-hakemistossa.
Versionhallinnan lokit.
Koodin kommentit. Kommentoi JavaDoc-kommentein kaikki ryhmän tekemät luokat ja rajapinnat sekä luokkien ja rajapintojen kaikki julkiset piirteet (metodit ja attribuutit). Javadoc-komentteja voi käyttää yhtenäisyyden vuoksi myös kätkettyjen piirteiden kommentointiin. Muista kommentoida “tavallisilla” rivi- ja lohkokommenteilla metodien vaikealukuiset osat.

Kaksi jälkimmäistä on mukana tietovarastossa itsenään eikä niitä liitetä PDF-dokumenttiin.

PDF-dokumentissa kuvataan:

Ryhmän toteuttaman ohjelman rakenne. Selkeä paperille käsin piirretty kaavio käy oikein hyvin, UML-luokkakaavio on helpointa tuottaa takaisinmallintavalla työkalulla. Esimerkiksi ilmainen UMLet osaa luoda luokkakaavion Java-koodista. Huomaa, että UMLetin kaltainen työkalu luo tyypillisesti vasta luokkakaavion aihion. Kaaviosta puuttuu todennäköisesti suurin osa luokkien välisistä suhteista, jotka on lisättävä kaavioon käsin. NetBeansille ei valitettavasti ole vakiintunutta asemaa saavuttanutta ilmaista takaisinmallintavaa liitännäistä.
Tärkeimpien luokkien vastuujako.
Ohjelman toiminta sekä jokainen vapaaehtoinen ominaisuus selkeästi kuvattuna.
Sovittu ja toteutunut työnjako.
Lyhyt käyttöohje.
Tiedossa olevat ongelmat tai puutteet.

Jos harjoitustyössä on käytetty tekoälyä, niin PDF-dokumentissa kerrotaan myös:

Missä ohjelman osissa on käytetty tekoälyä. Missä laajuudessa tekoälyä on käytetty kyseissä osissa. Mitä tekoälytyökaluja on hyödynnetty. Omat ajatukset tekoälyn käytön hyödyistä ja haitoista harjoitustyössä.

Dokumentin saa kirjoittaa itselle mieluisalla tavalla, mutta se tulee palauttaa PDF:nä. PDF-dokumentin tulee olla enintään viisi (5) sivua pitkä.