TEKNINEN MÄÄRITTELY PROJEKTITYÖ Tik-76.115
SISÄLLYSLUETTELO Sisällysluettelo... 2 Versiohistoria... 2 1. JOHDANTO... 3 1.1 Tarkoitus ja kattavuus... 3 1.2 Tuote ja ympäristö... 3 1.3 Määritelmät, merkintätavat ja lyhenteet... 3 1.4 Viitteet... 3 1.5 Yleiskatsaus dokumenttiin... 4 2. JÄRJESTELMÄN YLEISKUVAUS... 4 2.1 Sovellusalueen kuvaus... 4 2.2 Järjestelmän liittyminen ympäristöönsä... 4 2.3 Laitteistoympäristö(n kuvaus)... 4 2.4 Ohjelmistoympäristö(n kuvaus)... 4 2.5 Toteutuksen keskeiset reunaehdot... 4 2.6 Sopimukset ja standardit... 5 3. ARKKITEHTUURIN KUVAUS... 5 3.1 Ratkaisun "filosofia" (suunnitteluperiaatteet)... 5 3.2 Tietokanta-arkkitehtuuri... 5 3.3 Ohjelmistoarkkitehtuuri, moduulit ja prosessit... 5 4. MODUULI (JA PROSESSI) KUVAUKSET... 6 4.1 Kustakin moduulista (ja prosessista) kuvataan... 7 4.1.1 Yleiskuvaus... 7 4.1.2 Rajapinta... 7 4.1.3 Toteutus... 7 4.1.4 Virhekäsittely... 7 5. MUUT ERITYISET TEKNISET RATKAISUT... 7 6. HYLÄTYT RATKAISVAIHTOEHDOT... 7 7. VIRHEKÄSITTELY... 7 VERSIOHISTORIA Versio Päivämäärä Laatija Kuvaus 1.0-1 12.12.2000 JDu Ensimmäinen versio.
TEKNINEN MÄÄRITTELY 3 (7) 1. JOHDANTO Tässä dokumentissa kerrotaan kuinka tekninen osuus projektityöstä on tehty. 1.1 Tarkoitus ja kattavuus 1.2 Tuote ja ympäristö Tuote joka tässä projektissa tehdään on -ohjelma, mikä toimii Unix ja Linux ympäristössä. 1.3 Määritelmät, merkintätavat ja lyhenteet TÄTÄ PITÄÄ MUOKATA : Projektityön kohde. Ohjelma jonka tarkoituksena on etsiä haluttuja ominaisuuksia annetuista graafeista. Ohjelma kirjoitetaan isolla jos ohjelmasta puhutaan yleisesti tai viitataan projektityön nimeen. Kun varsinainen ohjelma koodataan, puhutaan wcliquesta pienellä alkukirjaimella. Tällöin tarkoitetaan ohjelman käynnistystiedostoa. Graafi: Useissa yhteyksissä tarkastellaan joukkoa somuja tai tiloja, joista joko on tai ei ole mahdollista siirtyä välittömästi toinen toisiinsa. Tyypillisiä esimerkkejä tällaisista ovat kartta, johon on merkitty kaupunkeja, sekä näiden väliset suorat liikenneyhteydet, tietokoneohjelman kulkua kuvaava vuokaavio ja sukupuut. Graafi, eli verkko G = ( V, E ) muodostuu äärellisistä joukoista V ja E, joista V on ns. solmujen joukko (solmuista käytetään myös joissain yhteyksissä nimityksiä kärki tai piste), ja E on sivujen joukko (käytössä myös nimitykset kaari ja haara). Algoritmi: Algoritmilla voidaan ratkaista olemassa olevasta graafista asioita, joista ollaan kiinnostuneita. Algoritmi jonka ympärille ohjelma rakennetaan on julkinen. Algoritmin toimintaa on kuvattu Internetissä seuraavissa dokumenteissa: "A Fast Algorithm for the Maximum Clique Problem" http://www.tcs.hut.fi/ ~ pat/paper1.ps "A New Algorithm for the Maximum-Weight Clique Problem" http://www.tcs.hut.fi/ ~ pat/paper2.ps Klikki: Klikki tarkoittaa yhteyttä usean solmun välillä Ansi c: Ohjelmointikieli, jolla ohjelma toteutetaan UML: "Unified Modeling Language" on ohjelmistotuotekehityksen standardikuvaamismenetelmä.
TEKNINEN MÄÄRITTELY 4 (7) 1.4 Viitteet TÄMÄ MYÖHEMMIN 1.5 Yleiskatsaus dokumenttiin TÄTÄ tarkennetaan myöhemmin ei oleellinen vielä kun ei kaikkia tarkasteltavia asioita ole määritelty. Mitä voidaan määritellä ja mitä ei tarvi määritellä. Johdanto osuudessa luodaan yleiskatsaus dokumenttiin. Siinä selvitetään termit, lyhenteet ja viitteet jotka auttavat lukijaa tutustumaan tähän dokumenttiin ja -ohjelmaan. Toinen luku tarkentaa ohjelmaa yleisellä tasolla. Jos lukija ei ole kiinnostunut pikkutarkasta ohjelman kuvauksesta, niin usein riittää tämän luvun lukeminen ohjelman idean ymmärtämiseksi. Arkkitehtuuri osuus kertoo tarvittavien tietokantojen osuudesta tähän projektiin. Työn luonteesta johtuen, tietokannat eivät ole suuressa merkityksessä tämän projektin missään suoritusvaiheessa. Neljänessä luvussa tarkennetaan toisessa luvussa esitettyjä ohjelman moduulien ominaisuuksia ja toimintoja. Luvut 5,6,7. Yhdessä läpi 2. JÄRJESTELMÄN YLEISKUVAUS Tavoitteena -ohjelmassa on koodata jo olemassaolevalle algoritmille toimiva ympäristö, jolloin algoritmin käyttö helpottuu ja algoritmille voidaan luoda uusia käyttötapoja. 2.1 Sovellusalueen kuvaus 2.2 Järjestelmän liittyminen ympäristöönsä 2.3 Laitteistoympäristö(n kuvaus) Standardi Unix / Linux käyttöympäristö. 2.4 Ohjelmistoympäristö(n kuvaus) Kokouksessa 12.12.00 2.5 Toteutuksen keskeiset reunaehdot Vaatimusmäärittelyn ehdot pätevät tässä, laajempi selvitys myöhemmin
TEKNINEN MÄÄRITTELY 5 (7) 2.6 Sopimukset ja standardit Standardit jota noudatetaan: Koodaus (Juha K) Sopimukset: Vaatimusmäärittely ja tekijänoikeus sopimus. 3. ARKKITEHTUURIN KUVAUS Tähän liitetään PowerPoint kuva joka NT hakemistossa (kesken, odottaa kommentteja). 3.1 Ratkaisun "filosofia" (suunnitteluperiaatteet) - perinteinen tapa, ei olioita, mallinnus kenties pseudokoodilla (käsittely kesken) - kussakin moduulissa paikalliset muuttujat, moduulien/funktioiden nimet kaikki alkavat wcxxx tai wc_xxx - c-kieli, asiakkaan vaatimus 3.2 Tietokanta-arkkitehtuuri viimesen kappaleen (tietokannan kenttien) soveltaminen: syötetiedoston tarkka määrittely tulostiedostojen tarkka määrittely 3.3 Ohjelmistoarkkitehtuuri, moduulit ja prosessit Tarkistetaan kokouksessa 12.12.00
TEKNINEN MÄÄRITTELY 6 (7) 4. MODUULI (JA PROSESSI) KUVAUKSET määritellään tähän jo kaikkien khdeksan toiminnon kutsut parametreineen nimeäminen, kuten jo edellä mainittu, kaikki alkaa wc:llä ja pieniä kirjaimia käytetään Tyyli- ym asioissa oppaamme on C-ohjelmointiopas, Kenneth Oksanen (btw, itse suosisin GNU-tyyliä ennemmin kuin K&R-tyyli; Oksanen sivu 9) koodi-templatet tulevat NT-hakemistoomme Syöte Järjestäminen 1 2 3 4 5 6 7 8 Tuloste 1=Painottamattomien klikkien laskeminen 2=Painotettujen maksimiklikkien laskeminen 3=Painottamattomien S kokoisten klikkien laskeminen 4=Painotettujen S kokoisten klikkien laskeminen 5=Painottamattomien, vähintään S kokoisten klikkien laskeminen. 6=Painotettujen, vähintään S kokoisten klikkien laskeminen. 7=Painottamattoman maksimi klikin koon laskeminen 8=Painotetun maksimi klikin koon laskeminen. Kuva 1. Liitynnät
TEKNINEN MÄÄRITTELY 7 (7) 4.1 Kustakin moduulista (ja prosessista) kuvataan 4.1.1 Yleiskuvaus Nämä tarkemmin viikoilla 51 ja 52. 4.1.2 Rajapinta 4.1.3 Toteutus 4.1.4 Virhekäsittely 5. MUUT ERITYISET TEKNISET RATKAISUT Tähän kommentteja Ossilta ja Juha L:ltä. 6. HYLÄTYT RATKAISVAIHTOEHDOT Onko näitä? 7. VIRHEKÄSITTELY Virhekäsittelyt virhetilanteissa kutsutaan aina virhekäsittelijää, jolle annetaaan virhekoodi parametrinä esim void errorhandler(int errno); virhenumerot listataan jossakin, ja listaa päivitettään voisi olla että modulin 1 virheet ovat välillä 1000-1999, modulin 2 välillä 2000-2999 jne Liitä kuvaus joka tehty palaverin 5.12 pohjalta, tarkenna error handleriä.
TEKNINEN MÄÄRITTELY 8 (7) 1. JOHDANTO Antaa yleiskuvan suunnittelusta. 1.1 Tarkoitus ja kattavuus Dokumentin tarkoitus, miksi tehty ja mihin tarkoitukseen, kenelle (oman firman toteutusporukka vaiko alihankkija vai kuka) tarkoitettu. Mitä asioita dokumentissa kuvataan. Varsinkin jos lukija ei ole tottunut lukemaan suunitteludokumentteja. Suunnittelun kattavuus suhteessa määrittelyyn. Esimerkiksi jos tämä suunnittelu kattaa määrittelyn poislukien käyttöliittymä ja tietokanta. 1.2 Tuote ja ympäristö Tuotteen nimi, tarkoitus ja tavoitteet. Tuotteen toimintaympäristö yleisesti. 1.3 Määritelmät, merkintätavat ja lyhenteet Sanat ja käsitteet jotka eivät ole lukijalle (tilaaja/toimittaja) tuttuja tai joiden voidaan ajatella tuottavan sekaannuksia erikoisella käytöllään tai jotka eivät yleisesti ole tiedossa. Nämä kannattaa esittää aakkosjärjestyksessä. Esim. ASCII-merkistöstä ilmoitetaan onko se 7-bittinen (esim. ISO 10646) tai 8-bittinen (esim. ISO 8859-1). 1.4 Viitteet Viittaukset muihin lähteisiin (dokumentit, standardit, käsikirjat). Viitteen mukaan aakkosjärjestyksessä Ne dokumentit joihin on viitattu tai jotka liittyvät systeemiin tai sen rakentamiseen, mikäli tarpeen (nimi, versio, päiväys, mistä löydettävissä). Lisätietoja. Koodaustyyliohje merkittäisiin tähän. Se tämän järjestelmän määrittelydokumenttihan on tärkein lisätietojen ja selvennysten lähde. Mikäli suunnittelu ei kata koko määrittelyä tulee se mainita tässä (eli mitä muita suunnitteluvaiheen dokumentteja on olemassa, jos on; esim. jos käyttöliittymän tai tietokannan suunnittelu on irrotettu omiksi dokumenteikseen). Luettelo aakkosjärjestyksessä. 1.5 Yleiskatsaus dokumenttiin Rakenteen kuvaus; sisältö ja organisointi; mitä missäkin luvussa käsitellään, tärkeää varsinkin mikäli lukija ei ole tottunut lukemaan em. sisällysluettelon mukaisia määrittelyjä.
TEKNINEN MÄÄRITTELY 9 (7) Mikäli ensimmäinen luku on kokonaisuudessaan samalla sivulla kuin tämä kohta (1.6 yleiskatsaus) tai jos 1. luku on muutoin kovin lyhyt, ei sitä tarvitse tässä kohdassa (1.6 yleiskatsaus) mainita vaan voidaan aloittaa 2. luvun asioista. Tässä mainitaan kustakin luvusta hieman enemmän kuin mitä pelkkä sisällysluettelon selaaminen kertoo. 2. JÄRJESTELMÄN YLEISKUVAUS Tässä voidaan mainita ohje dokumentin ja koodin kommenttien sekä muuttujien ja funktioiden yms. kielisyydestä. 2.1 Sovellusalueen kuvaus Se laajempi kokonaisuus johon tuote tai järjestelmä liittyy. Esimerkiksi TTKK:n opintotoimiston salivarausjärjestelmä. 2.2 Järjestelmän liittyminen ympäristöönsä Mitä järjestelmä tässä ympäristössä tekee. Käyttääkö kuvattu järjestelmä muita ohjelmia tai järjestelmiä, eli onko jonkin suuremman systeemin osa. 2.3 Laitteistoympäristö(n kuvaus) Laitteistoympäristö jossa ohjelma toimii. Esimerkiksi mitä oheislaitteita tarvitaan, mitä keskusyksiköltä odotetaan, mitä laitteiden ominaisuuksia ohjelma hyödyntää, mitkä laitteiston ominaisuudet rajoittavat teknisiä ratkaisuja, liittymät muihin tietokoneisiin. 2.4 Ohjelmistoympäristö(n kuvaus) Ohjelmistoympäristö jossa ohjelma toimii. Esimerkiksi käyttöjärjestelmä, kääntäjä, muut apuvälineet, tietokantaohjelmisto, tietoliikenneohjelmisto, www-selain, littymät muihin ohjelmistoihin/sovelluksiin, muut laitteistossa yhtä aikaa ajettavat ohjelmat. Luonnollisesti tarkkoine versioineen. 2.5 Toteutuksen keskeiset reunaehdot Jos asiakas on asettanut ohjelmalle huomattavan tärkeitä ehtoja (tai sellaisia on muista syistä) jotka on syytä ottaa huomioon suunnitelussa niin ne mainitaan tässä. Esimerkiksi laitteisto, ohjelmisto, lait tai asetukset, vasteajat. 2.6 Sopimukset ja standardit Jos käytetään standardien ja/tai eri sopimusten mukaisia suunnittelumenetelmiä, kuvaustapoja, dokumentointimalleja tms. niin ne mainitaan tässä. Samoin valmisosien käyttö ja niiden nimeämissäännöt.
TEKNINEN MÄÄRITTELY 10 (7) Myös erilaiset direktiivit, viranomaismääräykset ja ohjeistot mainitaan tässä, mikäli ne vaikuttavat suunnitteluun. Siis tässä voi mainita nimeltä ja kohdassa 1.5 näkyy koko lähde tarkasti. 3. ARKKITEHTUURIN KUVAUS Suunnittelutavoitteet sekä perusteet valitulle arkkitehtuurille eli miksi juuri tällainen arkkitehtuuri. Tässä kuvataan ohjelmiston arkkitehtuuri yleisellä tasolla: ylimmänkäsitetason (abstraktiotason) moduulit ja niiden väliset liittymät. 3.1 Ratkaisun "filosofia" (suunnitteluperiaatteet) Suunnitteluperiaatteet eli "ratkaisun filosofia" alkaa valinnasta teettekö "perinteistä" rakenteellista suunnittelua (SD) vaiko oliosuunnittelua (OOD) vai jotakin muuta. Tuon valinta ratkaisee millaista ajattelutapaa (lähestymistapaa ongelmaan) käytätte jatkossa. Eli millä tavalla ryhmänne lähestyy ongelmaa ja ratkaisee sen, yleinen lyhyt selostus. Perustelut mukaan kaikkiin ratkaisuihin ja päätöksiin. Tärkeätä ovat myös yhtenäiset moduulien kutsutavat sekä yhtenäiset suunnitteluratkaisut eli perusteet moduulijaolle. RATKAISUN FILOSOFIA tarkoittaa mm. seuraavaa (ei suoraan koodaamaan vaan mietitäänpä hetki mitä tehdään ettei tehdä mitä vaan): olioita vai "perinteinen" rakenteinen tapa mikäli oliokeskeinen toteutus niin mikä mallinnusmenetelmä merkkipohjainen vai graafinen näyttö asiakas-palvelin-arkkitehtuuri vai "perinteinen" asiakas-palvelin työnjako globaalit vai lokaalit muuttujat valmis TKHJ vaiko oma tietokanta vai pelkkä tiedosto tietokanta: relaatiokanta vaiko jokin muu tietorakenteet (esim. linkitetty lista vaiko kiinteä taulukko) moduuli/lohkojako (esim. käyttöliittymä, tulostustoiminnot) yleiskäyttöiset komponentit (esim. KL, toolbar, tiedostojen-käsittely), jos sellaisia on kaikkien syötteiden tarkastus heti vaiko oma virhetarkistusmoduuli muistin käsittely (RAM, levymuisti, välimuisti,...) ohjelmointikieli (vasteaika/reaaliaikaisuus/rinnakkaisuusvaatimukset?) käyttöliittymä: 4GL vai näyttökehitin vai rutiinikirjasto. Modulaarinen ohjelma koostuu osista, jotka voidaan poistaa tai vaihtaa ja joita voidaan lisätä. Kiinnitetty ohjelmointikieli voidaan se mainita tässä (periaatteessa suunnittelu voi vieläkin olla ohjelmointikieliriippumaton). Perusteluna ei kelpaa "ainoa jota osaan". 3.2 Tietokanta-arkkitehtuuri
TEKNINEN MÄÄRITTELY 11 (7) Kuvataan tietokanta-arkkitehtuuri yleisellä tasolla. Esimerkiksi jako tiedostoihin tai tietokantoihin, tiedostojen/tietokantojen väliset liittymät, tiedostojen/tietokantojen organisointi, käytettävät tietokantaohjelmistot (jos on), suojaukset, toipuminen, varmistukset, huolto, ylläpito. Perustelut mukaan luonnollisesti. Tietokannat sekä niiden rakenne (eli esim. taulut eli relaatiokuvaukset (mikäli toteutus tehdään relaatiotietokannalla!)). Muutama sana tietokanta-arkkitehtuurista. Suunnitteludokumentissa (viimeistään) määrätään tietokannan rakenne. Määrittelydokumentin kolmosluvussahan jo määritettiin kentät pituuksineen. Nyt sitten tarkennetaan tietokannan rakenne selväksi. Mikäli käytetään valmista tietokannan hallintajärjestelmää (TKHJ, engl. DBMS), osaisi systeemin käyttäjä alustaa tietokannan eli luoda ne tietokannan taulut. Mikäli käytössä on relaatiomallin mukainen tietokanta, taululla voi ymmärtää yhtä relaatiota. Yksi tietokanta voi sisältää useita relaatioita. Tietokannan taulussa on tietenkin useita rivejä. Relaatiolla tarkoitetaan sarakkeita. Kahden sarakkeen taulu on pienin relaatio. Tietokannan rakentaminenhan on tasapainoilua tietokannan koon ja hakunopeuden välillä. Ratkaisu on aina kompromissi. Tietokantaratkaisu kuvataan yksityiskohtaisesti ellei sitä ole tehty jo määrittelyssä. tietokantaratkaisun yleiskuva, tiedostot ja niiden väliset liittymät tietokantaa käyttävät muut ohjelmistot tai järjestelmät tietokannan tukiohjelmisto (esim. varmistukset, toipuminen, testaus) kustakin tietokannasta tai tiedostosta rakenne/organisointi tietuekuvaus tietokuvaus tyyppi käsittely- tai laskentasäännöt suhteet muihin tietoihin suhteet muihin tiedostoihin tai tietokantoihin päivityskriteerit ja -tavat tilavaatimukset ylläpitonäkökohdat varmistusnäkökohdat suojausnäkökohdat. Tietokannan kenttien kuvaus tarkasti; kentän nimi tai tunniste kentän merkitys kentän pituus ja muoto sallitut arvot. 3.3 Ohjelmistoarkkitehtuuri, moduulit ja prosessit
TEKNINEN MÄÄRITTELY 12 (7) Tämä kohta on ehkäpä tärkein suunnitteludokumentin asia. Älkää ohittako tätä kevyesti. Satunnaiselle dokumentin lukijalle tämä kohta kuvaa parhaiten suunnitteluanne (tarkat moduulikuvaukset selviävät selkeästä koodistakin). Usein kirjataan yksityiskohdat pikkutarkasti ylös, mutta laajempaa ja tärkeämpää kokonaiskuvaa ei anneta. Ohjelmistojako osajärjestelmiin / ohjelmiin / proseseihin / moduuleihin / pakkauksiin / luokkiin sekä niiden väliset liittymät yleisellä tasolla. Perustelut käytettyyn jakoon tulee selvittää. Tähän ennnen moduulikuvauksia kannattaa oheistaa kaavio, joka selvittää moduulien keskinäiset suhteet, eli mikä kutsuu mitäkin. Moduuli- eli arkkitehtuurikaavio voidaan esittää tässä tai mieluummin luvun 4 alussa, ennen moduulikuvauksia. Suunnitteludokumentin luvun 4 alkuun kannattaa liittää jonkinlainen moduulikutsukaavio, josta selviävät yhdellä silmäyksellä ohjelman sisältämät moduulit ja niiden riippuvuussuhteet (kutsusuhteet, sisältyminen (moduuli voi koostua moduuleista)) toisistaan. Mikäli toteutus on suunniteltu tehtäväksi jollakin oliokielellä, luokkahierarkia on selventävä lisäkaavio. Oliotekniikoissa voidaan käyttää selventävinä kaavioina luokkakaaviota, periytymiskaaviota ja kutsukaaviota (käyttökaavio). Vaikka tuotteen voisikin tehdä yksi ohjelmoija, tulee työ silti jakaa moduuleihin (muutosten ja myöhemmän käytön varalta). Moduuleihin jakohan mahdollistaa rinnakkaisen toteutustyöskentelyn 4. MODUULI (JA PROSESSI) KUVAUKSET Se moduulikaavio voisi sijaita tässä kohtaa (mieluummin kuin kohdassa 3.3). Moduulikaavio helpottaa ohjelman rakenteen ja toiminnan hahmottamista, etenkin jos ohjelma koostuu useammista kymmenistä moduuleista tai luokista. Siitä nähdään mikä vaikuttaa mihinkin. Haluttaessa voidaan moduulikaavioon lisätä selventäviä tekstejä kutsunuolien lisäksi mutta se ei ole välttämätöntä. Tekstin luettavuutta voidaan parantaa erilaisilla korostus- ja tehostuskeinoilla. Esimerkiksi aliohjelmien/funktioiden nimien kirjoittaminen eri kirjasinmallilla tai tekstin lihavointi (bold) tai kursivointi (italic). Eri seikkojen nimeämiseen kannattaa kiinnittää huomiota jo nyt (~tyyliohje). Esimerkiski moduulien, luokkien, funktioiden ja muuttujien nimeämiskäytäntöön.
TEKNINEN MÄÄRITTELY 13 (7) Mikäli joitakin nimiä (komennon parametrit, muuttuja, tiedosto, hakemisto) on jo kiinnitetty, niin ne mainitaan perusteluineen. Jokaisesta moduulista kuvataan sen tehtävä, liittymät muihin osiin sekä toteutusnäkökohdat. Moduuleista/luokista/pakkauksista tms. erotellaan valmisosat, eli muualta sellaisenaan tai muokaten napatut osat. Nämä seikat voisi helposti kuvata esim. moduulikaaviossa erilaisilla korostuskeinoilla. Tekniset yksityiskohdat tulee selvittää koodausta varten tarvittavalla tasolla Hyvin tehdyn moduulin tunnusmerkkejä; toteutustapa ei näy ulkopuolelle suorittaa vain yhden tehtävän mahdollisimman vähän, ja löyhiä kytkentöjä toisiin moduuleihin tiedonvälitys vain parametreilla, ei globaalia dataa mahdollisimman vähän parametreja aina selitetään selvästi, mikäli kuitenkin joudutaan käyttämään globaalia dataa parametreina vain sellaista tietoa, jota moduuli käyttää yksinkertainen sisäinen rakenne yksinkertaiset loogiset lausekkeet haarautumiskohdissa moduuli mahtuu yhdelle tai enintään kahdelle sivulle kaikilla moduuleilla samannäköinen vakionimiö (alkumerkintä eli header) esittelyt on kommentoitu koodi on kommentoitu vähintään lohkoittain. Älä tee liian rajoittuneita tai yleisiä moduuleja. Moduuli on rajoittunut, jos se suorittaa tarpeettoman yksityiskohtaisen tehtävän käsittelee rajoittuneita arvoja tai tyyppejä toimii vain tiettynä aikana (vuosiluvut kahdella numerolla...). Liian rajoittunutta moduulia ei voida käyttää muualla. Moduuli on liian yleinen, jos tekee tarpeettoman laajan tehtävän käsittelee liian monia arvoja tai tyyppejä saa parametrinaan tiedon, joka ei muutu. Liian yleistä moduulia ei voida hyödyntää riittävästi. 4.1 Kustakin moduulista (ja prosessista) kuvataan Moduulikuvauksissa on hyvä käyttää jotakin yhtenäistä merkintätapaa, "TYYLIOHJETTA", esim. muuttujien ja funktioiden nimeämiskäytännöissä (suomi/englanti, iso/pieni AlkuKirjainKäytäntö, alaviivoja_vaiko_ei,... ) 4.1.1 Yleiskuvaus Nimi:
TEKNINEN MÄÄRITTELY 14 (7) Heti ensimmäiseksi kerrotaan moduulin nimi. "Standardimuotoiset"moduulien otsikot eli nimiöt (header). Malleja on paljon, eräs esimerkki on tämän tiedoston loppupuolella. Tyyppi: Tyyppi ilmoitetaan esim. pääohjelma, funktio, aliohjelma, pakkaus,luokka, prosessi. Yleinen kuvaus: Yleisesti mitä moduuli tekee. 4.1.2 Rajapinta Liittymät muihin moduuleihin. Joka moduulilla täytyy olla formaali rajapintamäärittely (black box- tyyliin). Kaikki rajapinnat ovat erittäin tärkeä alue, jo virhemahdollisuuksienkin takia. Luettelo ohjelmista, joita tämä ohjelma kutsuu (jos käyttää) tai jotka kutsuvat tätä (jos kutsuvat). parametrit nimi moodi (IN, OUT, INOUT) tyyppi tarkoitus mahdolliset arvot pakollisuus rajoitukset Esim. milloin moduuli on kutsuttavissa tai ajoitukset. 4.1.3 Toteutus Ohjeita moduulisuunnittelua ja toteutusta varten; tyypillisestitoimintaa on hahmoteltu pseudokoodilla tai hankalat kohdat jopaohjelmakoodilla. Tietorakenteet: Mikäli on tarpeen selostaa moduulin sisäisiä tietorakenteita. Algoritmit Mikäli on käytetty erikoisia ratkaisuja. Myös käytetyt vakioalgoritmit mainitaan (esim. quicksort). 4.1.4 Virhekäsittely Poikkeus- ja virhetilanteet Tärkeää on selvittää miten moduulin tulee reagoida erivirhetilanteisiin. Tässä kohtaa viimeistään
TEKNINEN MÄÄRITTELY 15 (7) määritelläänvirheilmoitustekstien tarkka sisältö ja sanamuoto (jollei ole jomäärittelyssä), sekä ohjelman toiminta virheen jälkeen. Myös havaitut/oletetut virhetilanteet kannattaa rehellisyyden jadokumentin käytettävyyden nimissä kirjata. Mm.testaussuunnitelmaatehtäisiin rinnan määrittelyn ja suunnittelun kanssa. Virhetilanteista selvitetään mihin tilanteisiin varaudutaan miten toimitaan, kun tilanne kohdataan miten virheestä ilmoitetaan käyttäjälle mistä tilanteista yritetään toipua ja miten kerätäänkö virhetilastoa. 5. MUUT ERITYISET TEKNISET RATKAISUT Esimerkiksi seuraavia asioita, mikä tarpeellista. suojaukset, turvallisuus varmistukset toipumiset ylläpidettävyys joustavuus siirrettävyys tai kannettavuus. 6. HYLÄTYT RATKAISVAIHTOEHDOT Ne mietityt mutta hylätyt ratkaisuvaihtoehdot kannattaa kirjataperusteluineen johonkin sopivaan lukuun tai kohtaan. Seuraavadokumentin lukija näkee, että tuotakin on mietitty. Samoinjos te itsesattumoisin lukisitte omaa dokumenttianne puolen vuoden päästä, ette varmaankaan muistaisi mitä asioita on sitä tehtäessä mietitty. 7. VIRHEKÄSITTELY Virheilmoitusten tekstit tulee kiinnittää viimeistään nyt suunnittelussa (parempi olisi miettiä ne jo määrittelyssä). yleiset virhekäsittelysäännöt yleiset moduulit virheiden käsittelemiseksi virheilmoitusten tunnistaminen virheilmoitusten tallettaminen (muistiin, levylle) virheilmoitusten ryhmittely (vakavuus, käyttäjän vaiko järjestelmän) virheilmoitustekstit.
TEKNINEN MÄÄRITTELY 16 (7) Toiminta epänormaaleissa tilanteissa kuuluisi jo määrittelyyn, mutta viimeistään suunnittelussa on asiaan otettava kantaa. Esim. miten järjestelmä käyttäytyy virtakatkoksissa? "Nouseeko itse pystyyn" vai "jääkö jumiin"? Kannattaa panostaa siihen virheilmoitusten yhtenäisyyteen! Käyttäjä näkee ohjelmasta vain sen ja arvioi ohjelman "hyvyyttä" paljolti käyttöliittymän perusteella.