Sisältö

Dokumentin tulee sisältää seuraavaa:

1. Henkilötiedot

   Otsikko; tekijän nimi, opiskelijanumero, koulutusohjelma, vuosikurssi; päiväys.

2. Yleiskuvaus

   Yleinen kuvaus siitä, mitä on luotu. Tähän osioon voi monissa tapauksissa pitkälti lainata suunnitelmasta. Jos osioon on tullut olennaisia muutoksia suunnitelmaan nähden, niistä tulee mainita tässä. Jos aihe on mahdollista toteuttaa usealla eri vaikeusasteella, ilmaise myös, minkä tasoisena työ on lopulta mielestäsi toteutettu.

3. Käyttöohje

   Opastus ohjelman käyttöön: miten ohjelma käynnistetään? Mitä sillä voi tehdä? Mitä komentoja käyttäjällä on valittavanaan? Jne.

4. Ohjelman rakenne

   Ohjelman erottelu tärkeimpiin osakokonaisuuksiinsa, toteutuneen luokkajaon esittely. Minkälaisilla luokilla kuvaatte ohjelman ongelma-aluetta? Mitä ongelman osaa kukin luokka mallintaa? Mitkä ovat luokkien väliset suhteet? Entä millaisia luokkia käytätte ohjelman käyttöliittymän kuvaamiseen?

   Tässä kannattaa esittää myös mahdollisia muita ratkaisumalleja ja perustella valittu ratkaisu. Jos suinkin mahdollista, liittäkää mukaan jonkinlainen graafinen luokkakaavio (voitte käyttää esim. UML-luokkakaavionotaatiota, mutta se ei ole millään muotoa pakollista). Esitelkää luokkien keskeiset metodit. Huom. oleellista on vain se, mitä metodeilla tehdään, ei se, miten ne sisäisesti toimivat.

5. Algoritmit

   Sanallinen kuvaus käyttämistänne algoritmeista, eli siitä miten ohjelma suorittaa tarvittavat tehtävät. Esim. miten tarvittava matemaattinen laskenta tapahtuu? (kaavat mukaan) Miten algoritminne löytää lyhimmän tiereitin kahden kaupungin välille? Miten toteuttamanne pelin tekoäly toimii? Kaavioita tms. voi käyttää apuna tarpeen mukaan. Mitä muita ratkaisuvaihtoehtoja olisi ollut? Perustelkaa valintanne: Verratkaa toteutusta johonkin toiseen ratkaisuun, ja selittäkää miksi päädyitte juuri tähän.

   Tässä kohdassa on siis tarkoitus selostaa ne periaatteet, joilla ongelmat on ratkaistu, ei sitä, miten algoritmit koodataan. Siis ei luokkien tai metodien kuvauksia tai muitakaan Pythoniin tai ohjelmakoodiin liittyviä seikkoja tänne. Pseudokoodiesitys keskeisimmistä ei-tunnetuista algoritmeista on kuitenkin hyvä olla sanallisen kuvauksen tukena. HUOM! Jokaisessa työssä on aina algoritmeja, toiset ehkä yksinkertaisempia kuin toiset, moni aivan itse alusta saakka keksittyjä. Kuvaa tässä niistä muutama kaikkein olennaisin.

6. Tietorakenteet

   Minkälaiset kokoelmatyypit/tietorakenteet soveltuvat parhaiten ohjelmassa tarvittavan tiedon varastoimiseen ja käsittelyyn? Miksi? Mitä muita valintamahdollisuuksia olisi ollut? Käytittekö muuttuvatilaisia (mutable) vai muuttumattomia (immutable) rakenteita? Jos käytitte Pythonin valmiita tietorakenteita, ei niiden tarkkaa määrittelyä tarvitse esittää. Jos taas ohjelmoitte itse jonkin tietorakenteen, on sen toimintatapa selostettava.

7. Tiedostot

   Selostakaa tässä osiossa myös millaisia tiedostoja ohjelmasi käsittelee, jos mitään. Esim. ovatko ne tekstitiedostoja vai binaaritiedostoja, ja miten tieto on niissä esitetty? Kuvatkaa lopullinen tiedostoformaatti sillä tasolla, että assistentti voi halutessaan helposti luoda ohjelmalle testidataa. Jos ohjelma tarvitsee toimiakseen käyttäjän luomia asetustiedostoja tms. laittakaa ne lähdekoodin mukaan liitteeksi. Tarkoitus on palauttaa koodi sellaisessa muodossa että assari voi helposti kokeilla sitä käyttämättä paljon aikaa ohjelman käyttökuntoon virittelyyn.

8. Testaus

   Kertokaa miten ohjelmaa testattiin ja kuinka se vastasi suunnitelmassa esitettyä.

   Läpäiseekö ohjelma kaikki suunnitelmassa esitetyt testit? Kuinka ohjelmaa testattiin sitä rakennettaessa? Oliko testauksen suunnittelussa jotain olennaisia aukkoja? Yksikkö;testausta harjoiteltiin kurssin alkupuolella. Jos teit yksikkötestejä jollekin koodin osalle, niin kerro testauksesta tässä.

9. Ohjelman tunnetut puutteet ja viat Kuvaa tässä osiossa kaikki tuntemasi puutteet ja viat ohjelmassasi. Kerro miten korjaisit nämä ongelmat jos jatkaisit projektia. Mitä vähemmän assistentti löytää puutteita kohdista joiden väität toimivan sen parempi. Ole siis rehellinen.

10. 3 parasta ja 3 heikointa kohtaa Assistentti käyttää runsaasti aikaa tutustuessaan ohjelmaasi, mutta ei välttämättä näe ja tunne toteutustasi samalla tavoin kuin sinä. Jos ohjelmassa on joitakin kohtia joita itse pidät erityisen hyvinä, mainitse tässä niistä 1-3 kappaletta lyhyen perustelun kera. Jos ohjelmassa on kohtia jotka itsekin tiedät heikoiksi, voi mainita myös nämä. Tällöin mahdollisuus että nämä heikot kohdat dominoivat arvostelua vähenee huomattavasti. Tässä voi myös esittää sanallisesti kuinka olisi nämä asiat halutessaan korjannut.

11. Poikkeamat suunnitelmasta

    Teitkö jotain toisin kuin olit suunnitellut? Miksi? Osuiko suunnitelmaan laatimasi ajankäyttöarvio oikeaan? Miksei? Entä toteutusjärjestys?

12. Toteutunut työjärjestys ja aikataulu Kerro tässä yleisellä tasolla missä järjestyksessä projekti lopulta toteutettiin (mielellään myös päivämäärät). Missä poikettiin suunnitelmasta?

13. Arvio lopputuloksesta

    "Yhteenveto" ja itsearviointi joka voi toistaa yllämainittujakin asioita.

    Arvioikaa ohjelman laatua, kertokaa sen hyvistä ja huonoista puolista. Onko työssä oleellisia puutteita ja mistä ne johtuvat (mahdollinen hyvä perustelu dokumentissa voi korvata pienet puutteet)? Miten ohjelmaa olisi voinut tai voisi tulevaisuudessa parantaa? Olisiko ratkaisumenetelmien, tietorakenteiden tai luokkajaon valinnan voinut tehdä paremmin? Soveltuuko ohjelman rakenne muutosten tai laajennusten tekemiseen? Miksi tai miksi ei?

14. Viitteet

    Mitä kirjoja, nettisivuja tai muuta materiaalia olette käyttäneet? Kaikki lähteet tulee ilmoittaa, vaikka niihin kuuluisivat pelkkä kurssilla käyttämänne oppikirja ja perusluokkakirjastojen API-kuvaus.

15. Liitteet

    Kaikkein tärkein projektin liite on projektin koko lähdekoodi.

    Liitteeksi tulee lisäksi ainakin tekstipohjaisissa ohjelmissa laittaa muutama havainnollinen ajoesimerkki, jotka on kätevä tehdä unixympäristöissä script-ohjelmalla. script käynnistyy kirjoittamalla ``script `` ja päättyy painamalla CRTL-D tai unix shellissa exit. scriptin ollessa käynnissä se tallentaa tiedostoon kaiken ruudulle ilmestyvän sekä käyttäjän kirjoittaman syöteen. Graafisissa töissä ajoesimerkkejä ei vaadita, mutta muutama todellinen kuva ohjelman käytöstä joko erillisenä liitteenä tai käyttöohjeen yhteydessä ei tekisi pahaa. (Kuvia voi Linux- tai Windows ympäristöissä napsia painamalla Alt+PrintScreen-nappuloita, (Riippuen käyttöjärjestelmästä voit antaa joko tallenettavan kuvan nimen heti tai kuva on leikepöydällä, mistä sen voi tallentaa jonkin piirto-ohjelman kautta.)

    Koko ohjelman ohjelmakoodia ei ole tarkoitus kopioida projektidokumentin PDF:ä&;auml;n.

Palautusformaatti

Kuten projektisuunnitelmakin, dokumentti kirjoitetaan mielellään PDF:ksi (tekstinkäsittelyohjelmat ja LaTeX tuottavat pyydettäessä PDF:ää.. Dokumentin lopullinen versio palautetaan Rubyriciin kurssin aikataulun mukaisesti. Palautus tehdään zip-pakettina.

Dokumentinkin kirjoituksen voi halutessaan aloittaa ottamalla tämän sivun pohjaksi johonkin tekstieditoriin ja korvaamalla kuvaustekstit omalla tekstilläsi.