Joensuun yliopisto Tietojenkäsittelytieteen laitos 5.3.2010/ PV Ohjelmointyön ohje YLEISTÄ Ohjelmoinnin harjoitustyön tarkoituksena on perehdyttää opiskelija ohjelmointiongelman ratkaisemisen eri vaiheisiin ja antaa käsitys siitä, miten ongelmanratkaisuun liittyviä suunnitelmia, ohjelmia ja dokumentteja laaditaan. Hyvä dokumentointi helpottaa ohjelman ylläpitoa (muuttamista, korjaamista, täydentämistä), jonka osuus atk-työstä on varsin suuri. Ohjelmointitöissä opitaan myös ohjelmien testausta ja paneudutaan ohjelmointikurssilla opittuihin asioihin hieman yksityiskohtaisemmin. Työn alkuvaiheessa kannattaa ajatella työn laajuutta ja vaatimuksia niin, ettei työn laajuus tule liian suureksi. Ennen työn aloittamista palautetaan toteutussuunnitelma. Ellei palautettu ohjelma toimi oikein, dokumentoinnissa on pahoja puutteita tai virheitä tai testaus ei ole riittävän kattava, työ palautetaan korjattavaksi. Korjattu työ on jätettävä uudelleen tarkastettavaksi kuukauden kuluessa palautteesta. TÖIDEN ARVOSTELU Arvostelun lähtökohtana on arvosana 3. Mikäli työ on hyvin tehty ja huolellisesti dokumentoitu, arvosanaa korotetaan. Tehoton tai epäselvä ohjelma samoin kuin puutteellinen dokumentointi pudottavat arvosanaa. HUOM! Myös korjatusta työstä voi saada erinomaisen arvosanan. Arvostelussa kiinnitetään huomiota ratkaisualgoritmin ja sen toteutuksen selkeyteen sekä ohjelman käytettävyyteen (esim. joustava käyttöliittymä) ja luotettavuuteen (esim. tarkistusten kattavuus). Ohjelman tulee olla selkeä ja itsensä selittävä. Dokumentin täytyy sisältää kaikki tarpeelliset osat ja sen perusteella on saatava hyvä käsitys ohjelman rakenteesta ja toiminnasta. Ohjelman arvostelussa kiinnitetään huomiota lähinnä seuraaviin seikkoihin: mahdollisimman virheetön ja selkeä toiminta kaikissa tilanteissa ohjelman selväpiirteisyys ja jäsentely, luokkarakenne aiheeseen sopiva ja perusteltu ohjelmointikielen tehokas käyttö ja sen ominaisuuksien hyvä hallinta (olioohjelmointi) riittävät virhetarkistukset ohjelmakoodi ja sen kommentointi ulkoasultaan moitteetonta testaus niin monipuolisella aineistolla, että ohjelman kaikki haarat käydään läpi - kohtuuden rajoissa 1
testitulokset tarkistettuja Jos ohjelma ei täytä edellä mainittuja vaatimuksia riittäviltä osin, se voidaan palauttaa korjattavaksi. Dokumentin arvostelussa kiinnitetään huomiota siihen, että dokumentti sisältää vaaditut osat (tehtävän mukaan joustaen) riittävällä tarkkuudella. Dokumentin arvostelu nojautuu seuraaviin periaatteisiin: dokumentin avulla on voitava käyttää ohjelmaa tuntematta sen rakennetta yksityiskohtaisesti; tämä edellyttää selkeitä syöttö- ja tulostusmalleja dokumentti antaa kuvan ohjelman toiminnasta lukijalle, joka ei tunne käytettyä ohjelmointikieltä dokumentin tulee helpottaa ohjelmaan tarkemmin perehtymistä ja ohjelmalistauksen lukemista (dokumentti ei ole ohjelmalistauksen kopio!) dokumentin täytyy olla kieli- ja ulkoasultaan selkeä Mikäli dokumentissa on pahoja puutteita tai virheitä, se palautetaan korjattavaksi. Dokumentti voidaan palauttaa korjattavaksi myös kieliasun takia. Lisäksi katsotaan seuraavat seikat harjoitustyölle eduiksi: virhetarkistusten kattavuus tulostuksen selkeä ulkoasu ohjelman lyhyys ja tehokkuus toteutuksen yhtenäisyys luokkien, metodien ja muuttujien havainnollinen nimeäminen ohjelman ulkoasu dokumentin selkeys ja johdonmukaisuus dokumentin ulkoasu TOTEUTUSSUUNNITELMA Suunnitelmassa kuvataan ohjelman käyttöliittymä ja suunniteltu toteutustapa. 1. Miten käyttäjä käyttää ohjelmaa - mitä käyttäjältä kysytään ja mitä tulostuksia ohjelma antaa. Tämä voidaan kuvata lyhyellä esimerkillä miten ohjelman pitäisi toimia - mallitulosteet ajosta kuten demotehtävissä on annettu - käyttäjän antama syöte lihavoituna (suunnitelma tehdään tekstinkäsittelyohjelmalla). 2. Mitä luokkia ohjelma sisältää - luokkia oltava ainakin kolme, joista yksi sisältää pääohjelman omassa luokassaan. Luokasta kuvataan attribuutit, konstruktori (konstruktorit) ja millaisia metodeja luokassa on. Metodeista annetaan vain esittelyrivi eli kuten ne ohjelmassa esitetään. Esittelyrivi sisältää palautusarvon, metodin nimen ja metodin parametrit tyyppeineen. Jos metodin tarkoitus ei selviä edellisestä, niin tarvittaessa kerrotaan mitä metodi tekee. Kuitenkin tarkoitus on miettiä niin kuvaavat nimet luokille, 2
attribuuteille, metodeille ja parametreille, että niitä ei suunnitelmassa tarvitse selittää. TYÖN DOKUMENTOINTI Pelkät kommentoidut ohjelmalistaukset yksinään eivät riitä työselostukseksi, vaan harjoitustyöstä on aina laadittava kirjallinen dokumentti. Ohjelman rakenne, luokkahierarkia, algoritmit, tietotyypit, tiedostojen muoto ym. dokumentoitavat seikat ratkeavat yleensä jo ohjelman suunnitteluvaiheessa. Ne onkin syytä samalla kirjata ylös jo senkin takia, että siten myös itse ohjelmointityö helpottuu. Suunnitteluvaihe on muutenkin erittäin tärkeä osa harjoitustyötä, jotta tekijällä on jo alkuvaiheessa realistinen kuva työn vaativuudesta. Myös testiaineisto kannattaa laatia jo suunnittelun yhteydessä, jolloin siitä tulee tarpeeksi kattava. Työselostuksen runko syntyy siis suurelta osin jo ohjelman suunnitteluvaiheessa, joten ohjelman valmistuttua jäljelle jää lähinnä yksityiskohtien täydentäminen ja selostuksen puhtaaksikirjoitus. Dokumentoinnin tulee olla selkeä ja täsmällinen. Työselostus kirjoitetaan hyvällä suomen kielellä välttäen tarpeetonta erikoistermien ja tietokoneslangin käyttöä. Käsittelyn ja arkistoinnin helpottamiseksi työselostuksen ulkoasussa noudatetaan seuraavia sääntöjä: kaikki sivut (kansilehteä ja sisällysluetteloa lukuunottamatta) numeroidaan. Sisällösluettelon jälkeisen sivun sivunumero on 1. sisällysluettelossa mainitaan dokumentin numeroidut otsikot ja niiden sivunumerot sekä luetellaan kaikki liitteet liitteet numeroidaan juoksevasti monisivuiset liitteet varustetaan kukin omalla sivunumeroinnillaan pysty- ja sivumarginaalien on oltava riittävän leveät (= 2,5 cm) tekstin jaottelussa käytetään hierarkista kappalenumerointia ohjelmalistauksissa käytetään tasavälistä kirjasinta (esim. Courier); ohjelmalohkot sisennetään yhdenmukaisesti 3-6 välilyönnillä. Dokumentti sisältää seuraavat osat: Kansilehti ja sisällysluettelo Kansilehdeltä tulee ilmetä seuraavat tiedot: työn nimi ja koodi tekijän nimi ja opiskelijanumero palautuspäivämäärä HUOM! Kansilehti ja sisällysluettelo ovat omilla sivuillaan ja itse teksti alkaa sisällysluetteloa seuraavalta sivulta. 3
1. Tehtävän määrittely ja ratkaisuperiaate Dokumenttia laadittaessa on otettava huomioon, että dokumenttia käytetään varsin erilaisiin tarkoituksiin. Tästä luvusta täytyy voida nopeasti nähdä, mitä työ käsittelee ja mihin ratkaisu perustuu. 1.1 Tehtävän määrittely Tässä kohdassa selostetaan annetun tehtävän määrittely, käytettävät valmiit tiedostot sekä muut tehtävänantoon liittyvät seikat - mieluummin omin sanoin kuin tehtäväpaperin tekstiä toistaen. Tämä osio olisi hyvä tehdä huolella ja hyvin heti työn alkuvaiheessa. Suosittelemme tämän osan liittämistä myös projektisuunnitelmaan. Tämä osa on koko dokumentin kannalta keskeinen kohta, sillä se määrittelee tarkasti ne ongelmat, joihin ohjelma ja koko myöhempi dokumentaatio yrittää antaa ratkaisuja. 1.2 Ratkaisuperiaate Tehtävän ratkaisuperiaate selostetaan pääpiirteissään välttäen laitteisto-, ympäristö - tai ohjelmointikohtaisia termejä. Yleiset ratkaisuperiaatteet ja -kaavat kuvaillaan täsmällisesti (esim. yhtälöt, yleiset algoritmit jne.). Suositellaan, että keskeiset algoritmit esitellään yleiskielellä ja mahdolliset yhtälöt yleistä matemaattista merkintätapaa käyttäen. Tämä teksti on laadittava niin, että sen läpi lukemalla näkee, onko ohjelman tekijä ymmärtänyt tehtävän oikein. Käytetyt laskukaavat ym. on syytä esittää puuttumatta ohjelman tietorakenteisiin. Esitystavan on syytä olla mahdollisimman kansantajuinen, niin että ohjelmoinnista mitään ymmärtämätönkin käsittäisi ratkaisun periaatteen. Tämä kappale on myös erittäin tärkeä, sillä tämän perusteella arvostelija näkee, onko kaikkiin edellisessä kohdassa asetettuihin ongelmiin löydetty ratkaisua. Jos näin ei ole, on syytä perustella, miksi näin ei ole, tai tarkastaja voi antaa työn korjattavaksi. 2. Ohjelman käyttöohje Ohjelmaa on kyettävä käyttämään tutustumatta sen rakenteeseen tai sisäiseen toimintaan. Käyttöohjeen on siis oltava dokumentin itsenäinen osa, jonka avulla ohjelmaa pystyy käyttämään lukematta ohjelman toimintakuvausta tai ohjelmakoodia. Hyvä käyttöohje voidaan irrottaa muusta dokumentista ja ojentaa käyttäjälle. Älä siis kirjoita tähän lukuun ohjelman koodauksesta mitään. 2.1 Syötteet ja tulosteet Ohjelman tarvitsemat syöttötiedot ja -tiedostot kuvaillaan huolellisesti. Syötteistä on selvitettävä niiden välitystapa ohjelmalle sekä se, missä muodossa syötteet annetaan (Esim. komentoriviltä, napin painallukset, hiiren koordinaatit jne.). Ohjelman tulosteiden looginen sisältö kuvataan sanallisesti. Tässä koh- 4
dassa esitellään kaikki normaalit tulosteet, virheilmoitukset luetellaan kohdassa 2.2. Keskustelevan ohjelman syötteiden ja tulosteiden kuvaus on mielekkäintä yhdistää siihen järjestykseen, missä keskustelu etenee. Tässä siis kuvataan ohjelman eteneminen antaen väliin malliajon palasia. Malliajon esimerkit (esim. Courier fontilla) annetaan loogisesti sisältäen käyttäjän antamat syötteet lihavoituna. Tällöinkin virheilmoitukset kootaan seuraavaan kohtaan. 2.2 Ohjelman sisältämät tarkastukset ja virheilmoitukset Tässä kohdassa selostetaan ohjelman toiminta eri virhetilanteissa. Ohjelman on kyettävä varautumaan - jos ei kaikkiin, niin ainakin todennäköisimpiin - virhetilanteisiin. Tyypillisiä virheitä ovat esimerkiksi annetut virheelliset syötteet. Kustakin virhetyypistä selostetaan virheilmoitusteksti ja virheen (todennäköinen) syy sekä kuvataan menettely suorituksen jatkamiseksi. Virheilmoitustekstit on paikallaan esittää sopivassa loogisessa järjestyksessä tai virhetekstin mukaisessa aakkosjärjestyksessä. Mikäli virhe on niin paha, ettei ohjelman suoritusta voida jatkaa, on tämä mainittava. Lisäksi luetellaan ne virhetilanteet, joissa ohjelman suoritus keskeytyy käyttöjärjestelmän virheilmoitukseen. 2.3 Ohjelman rajoitukset Tässä luetellaan ohjelman toimintaa rajoittavat seikat. Rajoituksia ovat esimerkiksi suurin mahdollinen syöttötietojen määrä, syöttötietona annettavien merkkijonojen pituudet jne. Mikäli käyttäjä voi vaikuttaa rajoitteisiin, on kerrottava, miten tämä tapahtuu. Useimmiten rajoitusten muuttaminen tosin edellyttää muutoksia itse ohjelmakoodiin, mihin käyttäjällä ei ole oikeutta; tällaiset muutosohjeet annetaan luvussa 3. 2.4 Ajo-ohje Käyttöohje sisältää aina myös ohjelman ajo-ohjeen. Tässä kohdassa ilmoitetaan ohjelman kaikki luokat ja niiden sijainti (www-sivu). Miten suorituskelpoinen versio muodostetaan sekä kaikki tarvittavat aputiedostot. Tämän lisäksi annetaan vielä varsinainen ajo-ohje eli komentojono, jolla ohjelma saadaan käyntiin. Kaikkien työhön liittyvien tiedostojen on oltava tekijän ilmoittamassa wwwhakemistossa, josta työnohjaaja voi vaivattomasti käydä hakemassa tarvittavat lähdetiedostot ja lukea ohjelman API-dokumentaation. 3 Ohjelman toiminta Tämä luku on tarkoitettu henkilölle, joka haluaa muuttaa ohjelmaa tai on muuten kiinnostunut ohjelman toimintaperiaatteesta. Luvun tarkoituksena on hel- 5
pottaa ohjelmalistauksen lukemista. Ohjelman toiminta kuvataan suorasanaisesti. 3.1 Tietorakenteet Tässä kohdassa luetellaan ohjelman tietorakenteet (esimerkiksi taulukot, oliot) ja selitetään näiden merkitys ohjelman kannalta. Erityisesti on kerrottava, mihin tietorakenteita käytetään ja millaista tietoa ne pitävät sisällään. Tietorakenteita ja niiden käyttöä on selvintä havainnollistaa kuvin. 3.2 Ohjelman rakenne Ohjelman rakenteen kuvailu selvittää lyhyesti ohjelman keskeiset käsitteet ja yleisrakenteen. Kuvien käyttö on suotavaa. Tarkoituksena on kuvata tarkasti ohjelman luokkahierarkia. Erityisesti kannattaa kiinnittää huomiota luokkarakenteeseen ja siihen, miten luokkien toimintaa hyödynnetään. 3.3 Luokat, tietojäsenet ja metodit Kukin luokka kuvataan omassa alakohdassaan (3.3.1, 3.3.2 jne.). Kuvauksessa on käytävä ilmi periytymissuhteet ja toteutetut rajapinnat. Lisäksi esitellään luokan sisältämät luokkavakiot, tietojäsenet ja metodit sekä selitetään niiden merkitys. Luokan mahdolliset alustajat kuvataan ennen metodeja. Jos luokan esittämää tietorakennetta ei voida ymmärtää pelkän selostuksen perusteella, piirretään siitä kaavio. 3.4 Muutosohjeet Lyhyet ohjeet ohjelman rajoitusten muuttamiseksi voidaan antaa tässä kohdassa. Laajamittaisia muutoksia ei tarvitse kuvailla, mutta ne on syytä mainita. 4 Testaus Tämä dokumentin osa on tarkoitettu vakuuttamaan lukija siitä, että ohjelma toimii virheettömästi ainakin testitapauksissa. (HUOM! Testaus on tärkeä osa ohjelmointityötä ja on hyvä muistaa, ettei virheetöntä ohjelmaa ole olemassakaan. Esimerkiksi Windows sisältää noin 17 virhettä 1000 ohjelmariviä kohti, vaikka sitä on testaamassa useita satoja ihmisiä.) Ohjelma ajetaan ennalta laaditulla, riittävän kattavalla testiaineistolla. Kaikki testitulokset on aina tarkistettava. Odotettavissa olevat tulokset lasketaan tai etsitään kirjallisuudesta ja verrataan ohjelman antamiin tuloksiin. Ellei kaikkia tapauksia käytännön syistä kyetä kohtuullisella vaivalla testaamaan, on kuitenkin pyrittävä hyvään kattavuuteen niin, että lähes kaikki ohjelmarivit tulevat ainakin kerran suoritetuiksi ja tämä on jotenkin osoitettava. 6
Testausraportissa kerrotaan, millaisia tilanteita on testattu (esim. syöttö komentoriviltä, hiiren napin painallus, pelin loppuminen jne.), minkä vuoksi ja millaiset syötteet kussakin testiajossa on annettu. Testauksesta antaa yleiskuvan esimerkiksi taulukko, josta ilmenee, mitä milläkin testimateriaalilla on haluttu testata. Jos ohjelmaa muutetaan, on kaikki aiemmat testit ajettava uudelleen ja varmistuttava siitä, että muutettu ohjelma toimii edelleen oikein. Tarpeen mukaan ajetaan lisäksi kokonaan uusia testejä. Esimerkki testaustaulukosta. HUOM! Oikean testaustaulukon on testattava lähes kaikkia mahdollisia tapahtumia: Testin tarkoitus: Odotettu tulos: Saatu tulos: Liikutetaan pelaajaa nuolinäppäimillä pelin aikana ja testataan liikkuuko pelihahmo oikein syötteisiin nähden. Testaaan hyväksyykö ohjelma virheellisen päivämäärän (30.2.2004) Pelihahmo liikkuu nuolinäppäinten osoittamaan suuntaan näppäintä painettaessa. Ohjelma ilmoittaa päivämäärän virheellisyydestä Nuolinäppäin vasemmalle liikuttaa pelihahmoa vasemmalle, oikea oikealle ja ylös hypäyttää hahmoa. Tulos oli odotetun tuloksen mukainen. Liitteet Liitteiden samoin kuin varsinaisen dokumentinkin osalta on pyrittävä A4- kokoon. Liitteet numeroidaan ja monisivuiset liitteet varustetaan kukin omalla sivunumeroinnillaan. Liite 1: Tehtäväpaperi Tehtävänanto liitetään dokumentin mukaan. Mahdolliset tehtävänantoa koskevat muutokset tulee sopia työnohjaajan kanssa erikseen. Liite 2: Projektisuunnitelma Ohjaajalle työn alkuvaiheessa lähetty projektisuunnitelma on myös liitettävä dokumentin mukaan. Ohjaajan on siitä helppo katsoa, mikä oli tehtävän tarkempi määrittely ja millaisiin osiin ohjelma alunperin oli jaettu. Toteutus ei aina noudata alkuperäistä suunnitelmaa, mutta siitä tekijäkin näkee mitä alussa suunnitteli. Liite 3: Ohjelmalistaus Dokumenttiin liitetään ohjelman listaus eli ohjelmakoodi täydellisenä. Kukin sivu numeroidaan juoksevasti. 7
OHJELMAKOODI Ohjelmakoodin tulee sisältää oma dokumentointinsa. Ohjelmaa muutettaessa on muutostiedot kirjattava heti ainakin ohjelmakoodin selitteiksi, jottei dokumentin jonkin osan päivitys unohtuisi. Koodin luettavuuden helpottamiseksi teksti on aseteltava ja muotoiltava selkeäksi ja kauttaaltaan yhdenmukaiseksi kokonaisuudeksi. Nasevasti nimetyt tunnukset ilmaisevat enemmän kuin lyhyet selitteet. Nimeämiskäytännön tulisi olla yhden mukaista ja noudattaa Javalle annettuja yleisiä ohjeita. Ohjelmakoodin asettelun sekä muuttujien ja luokkien nimeämisen osalta tulee koodin vastata Javalle asetettuja yleisiä ohjeita, jotka löytyvät osoitteesta http://java.sun.com/docs/codeconv/. Koodin dokumentoinnin osalta on käytettävä Javadoc työkalua ja sen määrityksiä. Lisäksi on syytä tutustua myös Javan omiin ohjesivuihin Javadocin käytöstä. Javadoc-työkalun kotisivu: http://java.sun.com/j2se/javadoc/ Kuinka javadoc-ohjetiedostoja kirjoitetaan: http://java.sun.com/j2se/javadoc/writingdoccomments/index.html Javadocin käyttö Windowsissa: http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html Seuraavassa on kerrottu, minkälaisia tietoja jokaisen luokan ja metodin eteen on vähintään laitettu. Ennen jokaisen luokan alkua tulee kirjata kommentiksi seuraavat tiedot: kuvaus luokan tarkoituksesta laatija (@author) luokan versionumero ja version päivämäärä (@version) Jokaista metodia ennen tulisi olla seuraavat tiedot sisältävä kommentti: yksityiskohtainen toimintakuvaus metodin oikeellista toimintaa koskevat rajoitukset syöteparametrit merkityksineen (@param nimi selitys) palautusarvon tyyppi ja merkitys (@return selitys) mahdolliset poikkeukset, joita metodi voi aiheuttaa (@exception selitys) Lisäksi jokaisen yli 10 riviä pitkän metodin sisällä on yleensä kommentteja. 8