Joensuun yliopisto AN 10.6.1997
Tietojenkäsittelytieteen laitos (AN 27.7.1987)
OHJEITA OHJELMOINNIN HARJOITUSTYÖTÄ TEKEVILLE
YLEISTÄ
Ohjelmoinnin harjoitustöiden tarkoituksena on
perehdyttää opiskelija pienoiskokoisen ohjelmointiongelman
ratkaisemisen eri vaiheisiin ja antaa käsitys siitä, miten
ongelmanratkaisuun liittyviä suunnitelmia, ohjelmia ja dokument-
teja laaditaan. Ohjelmointitöissä opitaan myös ohjel-
mien testausta ja paneudutaan luennoilla opittuihin asioihin yksi-
tyiskohtaisemmin kuin luentokursseilla on mahdollista.
Ohjelmointityö voidaan aloittaa, kun vastaavan opintojakson
asiasisältö on omaksuttu. Työn tekemisen kaikissa vai-
heissa on syytä neuvotella työnohjaajan kanssa, vaikkei
suoranaisia vaikeuksia työn tekemisessä
esiintyisikään. Myös dokumentin rakenteen ja
sisällön yksityiskohdista on hyvä neuvotella
työnohjaajan kanssa. Työ on jätettävä tar-
kastettavaksi kahden kuukauden kuluessa työn antamisesta.
Työtä tarkastettavaksi jätettäessä tulee so-
pia työkritiikin ajankohta työnohjaajan kanssa.
Ellei ohjelma toimi oikein, dokumentoinnissa on pahoja puutteita tai
virheitä tai testaus ei ole riittävä, työ palau-
tetaan korjattavaksi. Korjattu työ on jätettävä
uudelleen tarkastettavaksi kuukauden kuluessa
työkritiikistä. Kaikki aiemmin tarkastettu materiaali on
myös palautettava. Korjattuna palautetusta työstä
järjestetään uusi työkritiikki.
TÖIDEN ARVOSTELU
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 dokumentoin-
ti pudottavat arvosanaa. 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 tulosteiden tulee olla selkeitä ja
itsensä selittäviä. Dokumentin täytyy
sisältää kaikki tarpeelliset osat ja sen perusteella
on saatava hyvä käsitys ohjelman rakenteesta ja toiminnas-
ta.
Ohjelman arvostelussa kiinnitetään huomiota
lähinnä seuraaviin seikkoihin:
- mahdollisimman virheetön ja selkeä toiminta kaikis-
sa tilanteissa
- riittävät virhetarkistukset
- ohjelmateksti ulkoasultaan moitteeton
- testaus niin monipuolisella aineistolla, että ohjelman
kaikki haarat käydään läpi - kohtuuden
rajoissa
- testitulokset tarkistettuja
Jos ohjelma ei täytä edellä mainittuja vaatimuksia, se
voidaan palauttaa korjattavaksi. Muuten katsotaan seuraavat seikat
eduiksi:
- ohjelmointikielen tehokas käyttö ja sen ominaisuuk-
sien hyvä hallinta
- virhetarkistusten kattavuus
- ohjelman selväpiirteisyys ja jäsentely sekä
aliohjelmien osuva käyttö
- tulostuksen selkeä ulkoasu
- ohjelman lyhyys ja tehokkuus
- toteutuksen yhtenäisyys
- tunnusten havainnolliset nimet
Dokumentin arvostelussa kiinitetään huomiota
lähinnä siihen, että dokumentti
sisältää vaaditut osat (tehtävän mukaan
joustaen) riittävällä tarkkuudella. Arvostelu nojautuu
seuraaviin periaatteisiin:
- dokumentin avulla on voitava käyttää ohjelmaa
tuntematta sen rakennetta yksityiskohtaisesti; tämä
edellyttää selkeitä syöttö- ja tu-
lostusmalleja
- dokumentin pitää antaa kuva 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.
TYÖN DOKUMENTOINTI
On muistettava, että ohjelmakoodi on itsessään osa oh-
jelman dokumenttia. Kuitenkaan ei koskaan voitane kaikkea tarpeellis-
ta tietoa sisällyttää ohjelmalistaukseen vaikeuttamat-
ta ymmärtämistä kohtuuttomasti. Kun ohjelman erillinen
dokumentti ja ohjelmakoodi ovat toisiinsa nähden sopusuhtaiset,
antavat ne yhdessä riittävät edellytykset ohjelmaan
perehtymiseen.
Dokumentti sisältää seuraavat osat:
Kansilehti ja sisällysluettelo
Kansilehdeltä tulee ilmetä seuraavat tiedot:
- työn nimi ja mahdollinen koodi
- tekijän nimi ja opiskelijanumero
- jättöpäivämäärä
Sisällysluettelossa mainitaan dokumentin numeroidut otsikot
sekä luetellaan kaikki liitteet.
Liitteet numeroidaan juoksevasti. Monisivuiset liitteet varustetaan
kukin omalla sivunumeroinnillaan.
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 - mie-
luummin omin sanoin kuin tehtäväpaperin tekstiä
toistaen.
1.2 Ratkaisuperiaate
Ratkaisuperiaate selostetaan pääpiirteissään
välttäen laitteiston ja ohjelmointikielen teknisiä
termejä. Käytetyt laskukaavat ym. on syytä
esittää puuttumatta ohjelman tietorakenteisiin. Esitystavan
on syytä olla mahdollisimman kansantajuinen. Tästä
kohdasta on saatava selville, onko työn tekijä
ymmärtänyt tehtävän oikein.
2 Ohjelman käyttöohje
Ohjelmaa on kyettävä käyttämään tutus-
tumatta sen rakenteeseen. Käyttöohjeen on siis oltava doku-
mentin 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.
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. Mahdollisista syöttötiedostoista on
annettava tiedoston nimen lisäksi tiedoston tyyppi (tekstitie-
dosto, kokonaislukutiedosto, ...) ja tarvittaessa myös tietueku-
vaukset.
Ohjelman tulosteiden looginen sisältö kuvataan sanallises-
ti. Tässä kohdassa 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ällöinkin virheilmoitukset
kootaan seuraavaan kohtaan.
2.2 Ohjelman sisältämät tarkastukset ja virheilmoitukset
Tässä kohdassa selostetaan ohjelman toiminta eri virheti-
lanteissa. Ohjelman on kyettävä varautumaan - jos ei kaik-
kiin, niin ainakin todennäköisimpiin - virhetilanteisiin.
Tyypillisiä virheitä ovat esimerkiksi annetut virheelliset
syötteet.
Kustakin virhetyypistä selostetaan virheilmoitusteksti ja vir-
heen (todennäköinen) syy sekä kuvataan menettely suo-
rituksen jatkamiseksi. Virheilmoitustekstit on paikallaan
esittää sopivassa loogisessa järjestyksessä tai
tekstin mukaisessa aakkosjärjestyksessä.
Mikäli virhe on niin paha, ettei ohjelman suoritusta voida jat-
kaa, on tämä mainittava. Lisäksi luetellaan ne virhe-
tilanteet, joissa ohjelman suoritus keskeytyy käyttö-
järjestelmän virheilmoitukseen.
2.3 Ohjelman rajoitukset
Tässä luetellaan ohjelman toimintaa rajoittavat seikat. Ra-
joituksia 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 rajoitteiden
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 se hakemisto, jossa
ohjelma sijaitsee, ohjelman lähdekielisen ja suorituskelpoisen
version nimi sekä kaikki tarvittavat aputiedostot. Kun ohjelma
toimitetaan levykkeellä, kerrotaan lyhyesti, millaisen
ympäristön ohjelma toimiakseen vaatii. Jos ohjelma koostuu
erillisistä kooditiedostoista, kuvataan ajo-ohjeessa myös
se, miten ohjelman lähdekielisestä versiosta muodostetaan
suorituskelpoinen versio.
Kaikkien työhön liittyvien tiedostojen samoin kuin hakemis-
tojenkin suojaukset on asetettava sellaisiksi, että
työnohjaaja voi vaivattomasti käynnistää ohjel-
man.
3 Ohjelman toiminta
Tämä luku on tarkoitettu henkilölle, joka haluaa muut-
taa ohjelmaa tai on muuten kiinnostunut ohjelman toimintaperiaattees-
ta. Luvun tarkoituksena on helpottaa ohjelmalistauksen lukemista. Oh-
jelman toiminta kuvataan suorasanaisesti. Keskeiset algoritmit
esitetään pseudokoodin avulla. Dokumentti saa
sisältää ohjelmakoodia vain poikkeustapauksissa (oh-
jelmalistaus on dokumentin liitteenä).
3.1 Yleiset muuttujat ja tietorakenteet
Tässä kohdassa luetellaan ohjelman yleiset vakiot, tyypit,
muuttujat ja tietorakenteet, selitetään näiden merki-
tys sekä esitetään tunnusten nimeämisessä
noudatetut säännöt. Tietorakenteita ja niiden
käyttöä on selvintä havainnollistaa kuvin.
3.2 Ohjelman rakenne
Ohjelman rakenteen kuvailu selvittää lyhyesti ohjelman kes-
keiset käsitteet ja yleisrakenteen. Kuvien, kaavioiden ja esi-
merkkien käyttö on suotavaa. Rakenneselostuksessa on
selvitettävä seuraavat asiat:
- ongelman ratkaisun keskeiset ideat täsmällisesti
(yhtälöt, algoritmit, kuvat jne.)
- ohjelman tärkeimpien osien tehtävät lyhyesti
- ohjelman moduulirakenne tai muu ohjelman osasten ryhmittelyperuste
3.3 Muutosohjeet
Lyhyet ohjeet ohjelman rajoitusten muuttamiseksi voidaan antaa tässä kohdassa.
Laajamittaisia muutoksia ei tarvitse kuvailla, mutta niistä voidaan
mainita.
3.4 Aliohjelmat
Kustakin aliohjelmasta esitetään otsikko sekä alioh-
jelman toiminta pääpiirteissään. Mahdolliset si-
vuvaikutukset ja muut sidokset toisiin aliohjelmiin on
selvitettävä.
4 Tila- ja aikavaativuus
Tila- ja aikavaativuusarvio on olennainen osa tietorakenteiden ja al-
goritmien työtä, jossa operaatioiden ja keskeisten algorit-
mien vaativuus analysoidaan sopivalla tarkkuudella. Muista
töistä tämä luku jätetään pois,
ellei erikseen muuta sovita.
5 Testaus
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.
Kaikki testitulokset on aina tarkistettava. Odotettavissa olevat tu-
lokset lasketaan tai etsitään kirjallisuudesta ja verrataan
ohjelman antamiin tuloksiin.
Ellei kaikkia tapauksia käytännön syistä
kyetä kohtuullisella vaivalla testaamaan koneella (esim. muis-
tialueen täyttyminen ja ylivuodot, joiden aikaansaamiseksi tar-
vittaisiin kohtuuton määrä syötteitä), on
joko suoritettava erittäin huolellinen pöytätestaus ja
laadittava selvitys sen tuloksista tai muutettava taulukoiden ym. ra-
joja testaukseen sopivammiksi - jälkimmäinen menettely on
suotavampi.
Testausraportissa kerrotaan, millaisia tilanteita on testattu,
minkä vuoksi, ja millaiset syötteet kussakin testiajossa on
annettu. Testauksesta antaa yleiskuvan esimerkiksi taulukko, josta
ilmenee, mitä milläkin testimateriaalilla on haluttu testa-
ta.
Jos ohjelmaa muutetaan, on kaikki aiemmat testit ajettava uudelleen
ja varmistuttava siitä, että muutettu ohjelma toimii edel-
leen oikein. Tarpeen mukaan ajetaan lisäksi kokonaan uusia
testejä.
Liitteet
Liitteiden samoin kuin varsinaisen dokumentinkin osalta on
pyrittävä A4-kokoon. Liitteet numeroidaan ja monisivuiset
liitteet varustetaan kukin omalla sivunumeroinnillaan. Jatkolomak-
keista on poistettava vetorei'itys.
Lyijykynämerkintöjä ei saa liitteisiin eikä doku-
menttiinkaan tehdä. Vain työn tarkastaja käyttää lyijykynää.
1 Tehtäväpaperi
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ä.
2 Ohjelmalistaus
Dokumenttiin liitetään ohjelman listaus eli ohjelmakoodi
täydellisenä, mielellään luontevasti sivutettuna.
Jatkolomakkeelle tulostetun listauksen sivuja ei tarvitse irrottaa
eikä tällöin myöskään numeroida.
3 Ristiinviittaustaulu
Jokaisen aliohjelman osalta mainitaan, mistä aliohjelmista
kyseistä aliohjelmaa kutsutaan ja mitä aliohjelmia kyseinen
aliohjelma kutsuu. Ristiinviittaustaulu on esitettävä tau-
lukkomuodossa, mahdollisesti osiin jaettuna.
4 Testiaineisto
Testiajot listataan ja liitetään dokumenttiin. Listausten
tulee olla aitoja ja niihin on kynällä
merkittävä, mitkä osat on annettu syötteenä.
Jos syötteitä ja tulosteita ei käytännön
syistä saada samaan listaukseen, on syötteet listattava
erikseen ja selvästi kynällä merkittävä,
mikä syöte on minkin tulosteen tuottanut. Listauksia ei saa
editoida.
5 Levyke
Jos ohjelma ja mahdolliset muut tiedostot jätetään
tarkastettavaksi levykkeellä, palautetaan levyke takaisin
työn tekijälle, ellei erikseen ole muuta sovittu.
6 Muu materiaali
Korjaukset dokumentoidaan työnohjaajan kanssa sovittavalla ta-
valla. Mikäli työ jätetään tarkastettavaksi
korjattuna, on liitettävä mukaan myös aiemmin tarkas-
tettu materiaali eli virheellinen ohjelmalistaus, dokumentti ja tes-
tiaineisto. Tarkastajan tekemiä merkintöjä ei saa
poistaa. Ellei näitä ohjeita noudateta, voidaan työ
hylätä.
OHJELMAKOODI
Ohjelman tulee mahdollisuuksien mukaan sisältää oma
dokumentointinsa. Ohjelmaa muutettaessa on muutostiedot syytä
heti kirjata ainakin ohjelmakoodin selitteiksi, jottei dokumentin
jonkin osan päivitys unohtuisi.
Koodin luettavuuden helpottamiseksi teksti on aseteltava ja muotoil-
tava selkeäksi ja kauttaaltaan yhdenmukaiseksi kokonaisuudeksi.
Nasevasti nimetyt tunnukset ilmaisevat enemmän kuin lyhyet se-
litteet. Nimeämisen tulee noudattaa dokumentin kohdassa 3.1
esitettyjä nimeämissääntöjä.
Kunkin moduulin alkuun kirjataan selitteeksi seuraavat tiedot:
- koodin sisältävän lähdekielisen tiedoston nimi
- moduulin versionumero ja version päivämäärä
- kuvaus moduulin tarkoituksesta
- luomispäivämäärä ja laatija
- muutospäivämäärät, muutosten
tekijät sekä lyhyet kuvaukset muutoksista
Aliohjelmat puolestaan varustetaan seuraavat tiedot
sisältävällä selitteellä:
- aliohjelman laatu (funktio vai proseduuri) ja nimi
- ytimekäs kuvaus aliohjelman toiminnasta
- syöteparametrit merkityksineen
- tulosparametrit merkityksineen
- palautusarvon tyyppi ja merkitys (vain funktioilla)
- tarvittaessa myös yksityiskohtainen toimintakuvaus ja
sidokset toisiin aliohjelmiin; algoritmikin voidaan
esittää tässä, ellei sitä
esitetä dokumentissa
- aliohjelman oikeellista toimintaa koskevat rajoitukset
- mahdolliset sivuvaikutukset
- luomispäivämäärä ja laatija
- muutospäivämäärät, muutosten
tekijät sekä lyhyet kuvaukset muutoksista
Lyhyisiin ja toiminnaltaan selväpiirteisiin aliohjelmiin
riittää suppeampikin selite. Kokoelma toisiinsa
läheisesti liittyviä aliohjelmia voidaan varustaa
yhdellä yhteisellä selitteelläkin, jossa edellä
mainittujen tietojen lisäksi kuvaillaan kokoelman
käyttötarkoitus.
Last updated: 10.06.1997