Nämä ohjeet on muokattu Asko Niemeläisen alkuperäisestä tekstistä "Ohjeita ohjelmoinnin harjoitustyötä tekeville" ja Marja Kuittisen tekstistä "Ohjeita Karel-harjoitustyötä tekeville".
KAREL-harjoitustyön tarkoituksena on perehdyttää opiskelija pienen ohjelmointiongelman ratkaisemisen eri vaiheisiin ja antaa käsitys siitä, miten ongelmanratkaisuun liittyviä suunnitelmia, ohjelmia ja dokumentteja laaditaan.
Harjoitustyön aiheet jaetaan "Ohjelmointia opettajille"-opintojakson lopussa. Työn tekemisen eri vaiheissa on syytä neuvotella työnohjaajan kanssa, mikäli tekemisessä esiintyy vaikeuksia. Dokumentin rakenteen ja sisällön yksityiskohdista on myös tarvittaessa hyvä neuvotella työnohjaajan kanssa.
Työ on palautettava tarkastettavaksi henkilökohtaisesti harjoitustyön ohjaajalle (Markku Hauta-Kasari) tiistaihin 30.11.1999 mennessä.
Ellei ohjelma toimi oikein, dokumentoinnissa on pahoja puutteita tai virheitä, tai testaus ei ole riittävä, työ palautetaan korjattavaksi. Korjattu työ on jätettävä uudelleen tarkastettavaksi kahden viikon kuluessa työkritiikistä. Kaikki aiemmin tarkastettu materiaali on myös palautettava. Korjattuna palautetusta työstä järjestetään tarvittaessa uusi työkritiikki.
Harjoitustyöt arvostellaan ja työstä annettava arvosana vaikuttaa 1/3 verran kurssin lopulliseen arvosanaan. Arvostelun lähtökohtana on arvosana 2. Mikäli työ on hyvin tehty ja huolellisesti dokumentoitu, arvosanaa korotetaan. Tehoton tai epäselvä ohjelma samoin kuin kehno dokumentointi pudottavat arvosanaa. Myös korjatusta työstä voi saada erinomaisen arvosanan.
Arvostelussa kiinnitetään huomiota ratkaisualgoritmin ja sen toteutuksen selkeyteen. 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:
Jos ohjelma ei täytä edellä mainittuja vaatimuksia, se palautetaan korjattavaksi. Muuten katsotaan seuraavat seikat eduiksi:
Dokumentin arvostelussa kiinnitetään huomiota lähinnä siihen, että dokumentti sisältää vaaditut osat riittävällä tarkkuudella. Arvostelu nojautuu seuraaviin periaatteisiin:
Mikäli dokumentissa on pahoja puutteita tai virheitä, se palautetaan korjattavaksi. Dokumentti voidaan palauttaa korjattavaksi myös kieliasun takia.
On muistettava, että ohjelmakoodi on itsessään osa ohjelman dokumenttia. Dokumentti ja ohjelmakoodi antavat yhdessä riittävät edellytykset ohjelmaan perehtymiseen.
Dokumentti sisältää seuraavat osat:
Kansilehdeltä tulee ilmetä seuraavat tiedot:
Sisällysluettelossa mainitaan dokumentin numeroidut otsikot sekä luetellaan kaikki liitteet.
Liitteet numeroidaan juoksevasti. Monisivuiset liitteet varustetaan kukin omalla sivunumeroinnillaan.
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. Luku koostuu seuraavista osista:
Tässä kohdassa selostetaan annetun tehtävän määrittely ja muut tehtävänantoon liittyvät seikat - mieluummin omin sanoin kuin tehtäväpaperin tekstiä toistaen.
Ratkaisuperiaate selostetaan pääpiirteissään välttäen laitteiston ja ohjelmointikielen teknisiä termejä. Esitystavan on syytä olla mahdollisimman kansantajuinen. Tästä kohdasta on saatava selville, onko työn tekijä ymmärtänyt tehtävän oikein.
Tämä luku on tarkoitettu henkilölle, joka haluaa muuttaa ohjelmaa tai on muuten kiinnostunut ohjelman toimintaperiaatteesta. Luvun tarkoituksena on helpottaa ohjelmalistauksen lukemista. Ohjelman toiminta kuvataan sanallisesti. Keskeiset algoritmit esitetään pseudokoodin avulla. Dokumentti saa sisältää ohjelmakoodia vain poikkeustapauksissa (ohjelmalistaus on dokumentin liitteenä). Ohjelman toiminnan lisäksi luku sisältää seuraavat osat:
Ohjelman rakenteen kuvailu selvittää lyhyesti ohjelman keskeiset käsitteet ja yleisrakenteen. Kuvien, kaavioiden ja esimerkkien käyttö on suotavaa. Rakenneselostuksessa on selvitettävä seuraavat asiat:
Kustakin uudesta käskystä esitetään otsikko sekä käskyn toiminta pääpiirteissään. Sidokset toisiin uusiin käskyihin on selvitettävä.
Lyhyet ohjeet ohjelman rajoitusten muuttamiseksi voidaan antaa tässä kohdassa. Laajamittaisia muutoksia ei tarvitse kuvailla, mutta niistä voidaan mainita.
Tämä dokumentin osa on tarkoitettu vakuuttamaan lukija siitä, että ohjelma toimii virheettömästi ainakin testitapauksissa. Ohjelma ajetaan ennalta laaditulla, riittävän kattavalla testiaineistolla. (Tämä pätee yleisesti kaikkiin ohjelmointikieliin, KAREL-työssä ohjelma testataan annetulla kentällä). Ellei kaikkia tapauksia käytännön syistä kyetä kohtuullisella vaivalla testaamaan, tällöin ohjelmalla on suoritettava erittäin huolellinen pöytätestaus ja laadittava selvitys sen tuloksista.
Testausraportissa kerrotaan, millaisia tilanteita on testattu, minkä vuoksi. 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ä.
Liitteiden samoin kuin varsinaisen dokumentinkin osalta on pyrittävä A4-kokoon. Liitteet numeroidaan ja monisivuiset liitteet varustetaan kukin omalla sivunumeroinnillaan. Lyijykynämerkintöjä ei saa liitteisiin eikä dokumenttiinkaan tehdä. Vain työn tarkastaja käyttää lyijykynää.
Tehtäväpaperi liitetään dokumenttiin alkuperäisenä. Mahdolliset tehtävänantoa koskevat muutokset tulee työnohjaajan vahvistaa tehtäväpaperiin tekemällään merkinnällä.
Dokumenttiin liitetään ohjelman listaus eli ohjelmakoodi täydellisenä, mielellään luontevasti sivutettuna.
Ohjelma jätetään tarkastettavaksi levykkeellä, joka palautetaan takaisin työn tekijälle viimeistään viimeisellä työkritiikkikerralla.
Korjaukset dokumentoidaan työnohjaajan kanssa sovittavalla tavalla. Mikäli työ jätetään tarkastettavaksi korjattuna, on liitettävä mukaan myös aiemmin tarkastettu materiaali eli virheellinen ohjelmalistaus ja dokumentti. Tarkastajan tekemiä merkintöjä ei saa poistaa. Ellei näitä ohjeita noudateta, voidaan työ hylätä.
Koodin luettavuuden helpottamiseksi teksti on aseteltava ja muotoiltava selkeäksi ja kauttaaltaan yhdenmukaiseksi kokonaisuudeksi. Nasevasti nimetyt tunnukset ilmaisevat enemmän kuin lyhyet selitteet.
Ohjaaja:
Markku Hauta-Kasari
Tietojenkäsittelytieteen laitos,
Huone M385, Puh. 3108,
Email: Markku.Hauta-Kasari@cs.joensuu.fi,
Vastaanotto: Keskiviikkoisin klo. 11-12