Erikoistyöohje
JOENSUUN YLIOPISTO OHJE
Tietojenkäsittelytiede 09.10.1997
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TIETOJENKÄSITTELYTIETEEN ERIKOISTYÖ (173314, 10 ov)
Tietojenkäsittelytieteen syventäviin opintoihin kuuluu eri-
koistyö, jonka laajuus on 10 opintoviikkoa. Erikoistyön tar-
koituksena on perehdyttää opiskelija tietojärjestelmien laa-
timiseen approbatur ja cum laude -tason kursseihin liittyviä
harjoitustöitä laajemman tehtävän puitteissa.
Erikoistyö on käytännönläheisempi kuin tutkielma, joka on
useimmiten johonkin aiheeseen perehtymistä kirjallisuuden
avulla. Eräissä tapauksissa erikoistyö voi olla tutkielman
kokeellinen vaihe.
Työskentelystä
Erikoistyön tekeminen vaatii keskittynyttä työskentelyä ja
sen tekemiseen on varattava aikaa viikoittain vähintään 20
tuntia. Usein työ liittyy kiinteästi laitoksen tutkimuspro-
jekteihin. Tällöin työn mahdollinen viivästyminen haittaa
ryhmän muiden jäsenten töiden etenemistä. Erikoistyö on saa-
tava valmiiksi yhdessä vuodessa ellei työtä aloitettaessa ole
toisin sovittu.
Erikoistyön luonne edellyttää jatkuvaa yhteydenpitoa opiske-
lijan ja työn ohjaajan välillä. Opiskelijan on annettava oh-
jaajalle kerran kuussa (tai ohjaajan hyväksymän muun aikatau-
lun mukaisesti) kirjallinen ja suullinen raportti, jossa hän
selvittää raportointikaudella suorittamansa tehtävät ja nii-
hin käyttämänsä ajan sekä seuraavalla kaudella suoritettavik-
si suunnittelemansa tehtävät. Liitteenä on malli kirjallisen
raportin muodoksi. Raportointitilaisuuksien lisäksi opiskeli-
ja ja ohjaaja pitävät työn kuluessa yhteisiä neuvotteluja,
joissa voidaan sopia työn määrittelyyn mahdollisesti tarvit-
tavista muutoksista.
Työtä aloitettaessa on opiskelijan laadittava ohjaajalta saa-
mansa kuvauksen perusteella vaatimusmäärittely ja annettava
se ohjaajalle hyväksyttäväksi. Vaatimusmäärittelyn ei tarvit-
se olla kaikilta osiltaan testattavissa. Esimerkiksi tehok-
kuuskysymysten osalta siinä voidaan todeta täsmällisten aika-
vaatimusten sijasta vain se, mitkä asiat ovat kriittisiä ts.
mihin asioihin on kiinnitettävä erityistä huomiota työtä teh-
täessä. Joissakin erikoistöissä työn tarkempi sisältö muotou-
tuu vasta työn kuluessa, mutta tällöinkin on syytä kirjoittaa
vaatimusmäärittely, jotta työn tekijällä ja ohjaajalla olisi
varmasti sama käsitys työn sisällöstä.
Arvostelu
Erikoistyöstä annettava arvosana riippuu työn ja sen dokumen-
toinnin laadullisesta tasosta sekä opiskelijan työskentelyta-
vasta ja aktiivisuudesta työn suorituksen aikana.
Ohjelmien ulkoasusta
Ohjelmien ulkoasussa on syytä noudattaa jotain yhtenäistä
käytäntöä.
Muuttujien nimet ja kommentit kirjoitetaan suomeksi ellei oh-
jaajan kanssa erikseen toisin sovita.
Kommentteja on syytä käyttää runsaasti. Jokaisen muuttujan
esittelyn yhteydessä on oltava selitys muuttujan merkitykses-
tä. Funktioiden ja proseduurien kuvaukset on oltava kunkin
funktion ja proseduurin alussa itse ohjelmatekstissä liittenä
olevan esimerkin mukaisesti.
Dokumentointi
Dokumentoinnissa ovat tärkeintä asiasisältö ja selkeä esittä-
minen. Vähemmän tärkeää ovat ulkoasuun liittyvät kysymykset.
Dokumenttien viimeistelty ulkonäkö ei tietenkään ole haitak-
si, mutta sille ei anneta arvostelussa keskeistä sijaa. Työn
tuloksena syntyvä ohjelmisto on tarkoitettu ylläpidettäväksi,
joten myös sen dokumentaatiota joudutaan myöhemmin muutta-
maan. Siten ei ole mitään mieltä tuottaa dokumentteja esimer-
kiksi sellaisella järjestelmällä, joka ei ole ylläpitäjien
käytettävissä. Dokumenttien laatimisväline onkin aina erik-
seen sovittava ohjaajan kanssa.
Erikoistyön dokumentti koostuu normaalisti kolmesta osasta,
jotka ovat toisistaan täysin erillisiä:
- mainos
- käyttöohje
- ohjelmaselostus
Se, että osat ovat täysin erillisiä tarkoittaa, että sekä
käyttöohjeella että ohjelmaselostuksella on oma kansilehten-
sä, oma sisällysluettelonsa jne. Näillä kolmella osalla on
eri lukijakunnat, joten ne eivät saa viitata toisiinsa. Oh-
jelmaselostuksen lukijalla voidaan olettaa olevan käytössään
käyttöohje, joten käyttöohjetta ei tarvitse toistaa ohjelma-
selostuksessa. Muuten yleiskuvausten toistaminen tarvittavis-
sa määrin on sallittua ja jopa suositeltavaa.
Kaikki kolme dokumenttia on toimitettava paperimuodossa.
Vaikka ohjelman käyttöohjeesta olisi olemassa täydellinen
tietokoneella luettavissa oleva versio, niin siitä on tehtävä
myös paperilla oleva kunnollinen versio (ts. ei pelkkä nippu
erillisten sivujen listauksia) tai ainakin erillinen paperil-
la oleva alkeisopas, jonka voisi ajatella annettavaksi ohjel-
miston käyttöä aloittelevalle henkilölle. Lisäksi koneella
oleva versio on tulostettava kokonaisuudessaan paperille
(työn tarkastamisen ja arvostelemisen helpottamiseksi).
Mainos
Mainos on yhden sivun mittainen kuvaus ohjelmistosta, jonka
voisi sijoittaa (ulkoasun muotoilemisen jälkeen) johonkin
atk-alan lehteen. Mainoksessa tulee kuvata lyhyesti ohjelmis-
ton tarkoitus, sen olennaisimmat piirteet, kilpaileviin tuot-
teisiin nähden hyvät asiat, käyttöympäristö ja laite- sekä
ohjelmistovaatimukset. Mainoksen tulee olla myyvä mutta kui-
tenkin totuudenmukainen. Mainosta laatiessa on syytä muistaa,
että sen lukijalla ei ole mitään ennakkokuvaa esiteltävän oh-
jelmiston käyttötarkoituksesta.
Käyttöohje
Käyttöohje on tarkoitettu ohjelmiston normaalille käyttäjäl-
le, jonka tulee sen avulla pystyä käyttämään ohjelmistoon
kuuluvia osia sekä ymmärtämään ohjelmiston ja omien varsi-
naisten työtehtäviensä välinen yhteys. Käyttöohje voidaan ra-
kentaa periaatteessa kahdella tavalla: kädestä pitäen johdat-
televaksi alkeisoppikirjaksi tai kaikki yksityiskohdat tar-
kasti luettelevaksi käsikirjaksi.
Käyttöohjeessa tulee olla hyvät apuneuvot tietojen hakemisek-
si. Esimerkiksi sisällysluettelon tulee olla kuvaava. Se voi
matkia järjestelmän päävalikkoja tai olla käyttäjän työnkulun
mukainen. Pitkä käyttöohje ei välttämättä ole helppokäyttöi-
nen. Toisinaan onkin syytä jättää alimman tason otsikot pois
sisällysluettelosta. Lisäksi olisi hyvä, jos käyttöohjeen lo-
pussa olisi aakkosjärjestyksessä oleva hakusanaluettelo, jon-
ka avulla käyttäjä löytää kaikki ne sivut, joilla hakusana
esiintyy.
Käyttöohjeen alussa on oltava kunnollinen kuvaus ohjelmiston
käyttöalueesta ja -tarkoituksesta. Tämän perässä on varsinai-
nen käyttöohjeosuus. Lopussa on vielä oltava ohjelmiston
asennusohje. Asennusohje on kirjoitettava ajatellen henkilöä,
joka saa tarvittavat lähdekieliset ohjelmatiedostot ja muut
tarvittavat tiedostot nauhalla tai levykkeellä, jonka hän
osaa lukea johonkin omaan hakemistoonsa. Siten asennusohjees-
sa ei saa viitata tietyn koneen tiettyyn hakemistoon, josta
ohjelmisto on haettava.
Käyttöohjeen tulee sisältää (aakkos)järjestyksessä oleva
luettelo virheilmoituksista. Siinä on oltava itse virheilmoi-
tustekstin lisäksi ne toimenpiteet, jotka järjestelmä on il-
moituksen antamisen lisäksi tehnyt. Ilmoituksen syistä on
kerrottava paitsi välitön syy (joka normaalisti selviää jo
itse ilmoitustekstistä) myös tavanomaiset välilliset syyt,
joista johtuen virhetilanteeseen on päädytty. Lisäksi on ker-
rottava, millä eri toimenpiteillä käyttäjä voi jatkaa virhe-
tilanteen jälkeen.
Käyttöohjeessa on varottava passiivin käyttöä. Ilmaisu
"näytölle kirjoitetaan uudet tiedot" ei anna lukijalle min-
käänlaista vihjettä siitä, tekeekö kyseisen työn tietokone
vaiko käyttäjä itse. Käyttäjään voi hyvin viitata sinuttele-
malla ("anna vastauksena tiedoston nimi, jonka jälkeen ohjel-
ma tuo tiedoston sisällön näytölle").
Ohjelmaselostus
Ohjelmaselostus on kirjoitettava ikäänkuin lukijana olisi sa-
mantasoinen opiskelija, joka joutuu tekemään ohjelmistoon
jonkin muutoksen. Siten tärkeintä on kuvata ohjelmiston
yleisrakenne ja tärkeimmät ratkaisuperiaatteet, jotta muutok-
sen tekemiseksi tarvittavat seikat olisi mahdollista keksiä
ja lisäksi halutut kohdat olisi helppo löytää. Sen sijaan yk-
sinkertaisia yksityiskohtia on turha käsitellä. Jos työssä on
käytetty jotain tavanomaisesta poikkeavaa toteutusvälinettä,
niin selostuksen on oltava tavanomaista tarkempi.
Vaatimusmäärittely sekä työskentelyn aikana mahdollisesti
tehdyt suunnitteludokumentit, joiden sisältö ei luontevasti
sulaudu osaksi ohjelmaselostusta, laitetaan ohjelmaselostuk-
sen liitteiksi.
Ohjelmaselostuksessa on kuvattava ainakin seuraavat asiat:
- Ohjelmiston tarkoitus: mihin asiakokonaisuuteen ohjelmisto
liittyy; millaisissa tehtävissä ohjelmistosta on apua; mitä
ohjelmistolla on tarkoitus tehdä
- Ohjelmiston toimintaperiaate: ojelmiston toiminnan yleiset
periaatteet; käytettävien erikoisalgoritmien nimet tai
yleisen tason kuvaukset; tiedostojen tavanomaisesta poik-
keavat käyttöperiaatteet; muut ohjelmat, joihin laadittu
ohjelmisto liittyy; muualta valmiina (tai osittain valmii-
na) saadut osat
- Ohjelmiston jako pääosiinsa: erilliset ohjelmat ja niiden
liittyminen toisiinsa; yksittäisten ohjelmien tärkeimmät
komponentit; tässä kohdassa on syytä esittää kaavio, jossa
on 5-10 osaa ja niiden väliset yhteydet
- Tietorakenteet: tärkeimmät tietorakenteet ja niiden käyttö-
periaatteet; tärkeimmät muuttujat ja niiden merkitys; esi-
merkki tietorakenteiden sisällöstä mielellään kuvana
- Moduulien kuvaukset: moduulin tarkoitus ja toimintaperiaat-
teet; luettelo funktioista ja niiden kuvaus niiden kutsu-
suhteista; yksittäisten funktioiden ja proseduurien kuvauk-
set on oltava kunkin funktion ja proseduurin alussa itse
ohjelmatekstissä, jonka johdosta näitä asioita ei tarvitse
toistaa enää ohjelmaselostuksessa
- Ohjelmiston muuttaminen: helposti muutettavissa olevat
piirteet ja ohjeet näiden muutosten tekemiseen (esimerkiksi
muutettavissa olevien vakioiden kelvollisten arvojen
rajat); luettelot kohtuutyöllä muuttettavissa olevista omi-
naisuuksista sekä ominaisuuksista, joiden muuttaminen vaa-
tii koko ohjelmiston uudelleentekoa
- Ohjelmiston käsittelyohjeet: jako hakemistoihin ja tiedos-
toihin; versiohallintamenetelmä; kääntämisohjeet
- Testaus: yksikkötestin haluttu kattavuus; testitapaushake-
miston kuvaus; ohjeet testitapausten suorittamiselle; pe-
rustelut kattavuuden toteutumiselle; vastaavat asiat integ-
rointitestaukselle
Testitapauksien suunnittelun on pohjauduttava jollekin katta-
vuusperiaattelle (esim. 98 % kattavuus ohjelmakoodille ja li-
säksi jokainen testi saa vähintään kerran kunkin yksittäisen
tulosmahdollisuutensa). Tältä pohjalta on muodostettava jouk-
ko testitapauksia, jotka täyttävät vaaditun kattavuuden. Oh-
jelmaselostuksessa on kuvattava kattavuuden täyttyminen niin
tarkaan, että lukija vakuuttuu testitapausten riittävyydestä.
Testien suoritus ja tulosten vertailu odotettuihin tuloksiin
on automatisoitava mahdollisimman pitkälle.
ESIMERKKI FUNKTION DOKUMENTOINNISTA OHJELMAKOODISSA
/****************************************************************
Funktio: aika_ero
Viitteet: Vaatimusmäärittely 5.4.7.12
Kuvaus: Kahden kellonajan erotus
Kutsu: ero = aika_ero(alku,loppu,yksikko);
Syöteparametrit:
char *alku Alkuajankohta date-komennon
palautamassa muodossa, esim.
Tue Feb 11 10:09:30 EET 1992
char *loppu Loppuajankohta samassa muodossa
int yksikko Tulokselle haluttu yksikkö: SEKUNTI
tai SADASOSASEKUNTI
Tulosparametrit: Ei ole
Palautusarvo: long Syöteparametreina annettujen ajankoh-
tien erotus pyydetyissä yksiköissä; 0
jos parametrit eivät ole vaadittua
muotoa
Esimerkki: char *aika;
long kesto;
...
kesto = aika_ero("Tue Feb 11 10:09:30 EET 1992",aika,
SEKUNTI);
Toiminta: Funktio palauttaa parametreina annettujen ajankohtien
erotuksen sekunneissa (jos yksikko on SEKUNTI) tai
sekunnin sadasosissa (jos yksikkö on
SADASOSASEKUNTI).
Rajoitukset: Alkuajankohta ei saa olla loppuajankohdan jälkeen.
Jos on, niin funktio palauttaa arvon 0.
Ulkoiset vaikutukset: Ei ole << Tähän syöttö ja tulostus >>
Sivuvaikutukset: Ei ole
Globaali ohjaus: Ei ole
Katso myös: ero_minuuteissa
Historia: 11.02.1992 Heikki Heikäläinen
12.02.1992 Matti Meikäläinen
- palautusarvo int:istä longiksi
****************************************************************/
ERIKOISTYÖN KUUKAUSIRAPORTTI
Nimi: ___________________________________________
Raportointikausi: ___.___.200__ - ___.___.200__
Ajankäyttö raportointikaudella:
: Määrittely : Suunnittelu : Toteutus : Testaus : Muu : Yht.
: : : : : :
: _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
Raportointikaudella tehty:
Seuraavan raportointikauden tehtävät:
Työn etenemistä mahdollisesti haittaavat seikat:
Allekirjoitus: __________________________________________
AJANKÄYTÖN KERUULOMAKE
Nimi: ___________________________________________
Raportointikausi: ___.___.200__ - ___.___.200__
Merkitse ajankäyttö päivittäin puolen tunnin tarkkuudella. Dokumen-
tointi merkitään siihen sarakkeeseen, johon kuuluvaa työtä dokumen-
toidaan. Käyttöohjeen kirjoittaminen merkitään kohtaan "Määrittely".
Käytä lomaketta syklisesti: jos raportointikausi alkaa kuun 20.
päivä, niin aloita 20. päivän kohdalta ja jatka seuraavan kuun alussa
ensimmäiseltä riviltä.
Päivä : Määrittely : Suunnittelu : Toteutus : Testaus : Muu : Yht.
: : : : : :
1 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
2 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
3 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
4 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
5 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
6 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
7 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
8 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
9 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
10 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
11 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
12 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
13 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
14 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
15 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
16 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
17 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
18 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
19 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
20 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
21 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
22 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
23 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
24 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
25 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
26 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
27 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
28 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
29 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
30 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
31 : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
: : : : : :
Yht. : _ _ _ _ _ _: _ _ _ _ _ _ : _ _ _ _ _: _ _ _ _ : _ _ : _ _ _
Last updated: October 9, 1997
saja@cs.joensuu.fi