Olio suunnittelu: http://www.cs.helsinki.fi/u/taina/ohtu/s-2000/luennot/ol_suunn/kaikki.html Tkk pohja http://mordor.cs.hut.fi/tik-76.115/template/teknpohja.htm vielä yksi: SUUNNITTELUDOKUMENTTI SISÄLLYSLUETTELORUNKO TTKK/OHJ:n paljon mukailema ANSI/IEEE 1016-1987 (tekninen määrittely) 1. JOHDANTO 1.1 tarkoitus 1.2 tuote 1.3 dokumentin kattavuus 1.4 määritelmät, merkintätavat ja lyhenteet 1.5 viitteet 1.6 yleiskatsaus dokumenttiin 2. JÄRJESTELMÄN YLEISKUVAUS 2.1 sovellusalueen kuvaus 2.2 järjestelmän liittyminen ympäristöönsä 2.3 laitteistoympäristö(n kuvaus) 2.4 ohjelmistoympäristö(n kuvaus) 2.5 toteutuksen keskeiset reunaehdot 2.6 sopimukset ja standardit 3. ARKKITEHTUURIN KUVAUS 3.1 ratkaisun "filosofia" (suunnitteluperiaatteet) 3.2 tietokanta-arkkitehtuuri 3.3 ohjelmistoarkkitehtuuri, moduulit ja prosessit 4. MODUULI (JA PROSESSI) KUVAUKSET 4.x kustakin moduulista (ja prosessista) kuvataan esimerkiksi 4.x.1 yleiskuvaus 4.x.2 rajapinta 4.x.3 toteutus 4.x.4 virhekäsittely 5. MUUT ERITYISET TEKNISET RATKAISUT 6. HYLÄTYT RATKAISVAIHTOEHDOT 7. VIRHEKÄSITTELY (ellei selostettu täydellisesti 4. luvussa) < ja seuraavista asioista lisälukuja tarpeen mukaan... > Ylläpito Testattavuus Jäljitettävyys Siirrettävyys Turvallisuus Luotettavuus Ratkaisun rajoitteet Virhetilanteiden käsittely (jos ei muualla) Käyttöliittymä (jos ei tarkasti määrittelyssä) Tietokanta (jos ei tarkasti määrittelyssä tai kohdassa 3.2) Seuraavilla sivuilla on kukin kohta selostettu tarkemmin. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - TTKK / Ohjelmistotekniikka, http://www.cs.tut.fi/ Tämän dokumentin muokkasi ja mukaili Tero Ahtee, tensu@cs.tut.fi - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - VAIN OTM-KURSSILLA, EI NORMAALISTI: muutokset aiempiin tietoihin (määrittelydokumentti) kirjataan tarkasti (esim. käyttöohjeen ajan tasalla pitäminen olisi hyvin tärkeää). Muutoksista kannattaa kirjata päiväys, muutoksen syy ja muutoksen tekijä. Kirjatkaa ne lisäykset, poistot ja muutokset, joita suunnittelun aikana olette huomanneet määrittelyyn nähden, sopivalla tavalla. Normaalistihan kun tällaisia kohtia tulee esiin, määrittelydokumentti päivitettäisiin (ja kenties katselmoitaisiinkin ja hyväksytettäisiin) ja vasta sen jälkeen jatkettaisiin suunnittelua. Moduulikavion voi piirtää millä tahansa välineellä. Oliototeutuksessa piirretään luokkakaavio. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Voi sitä onnetonta, joka vielä kirjoittaa moduuli yhdellä u-kirjaimella. Nimi saatetaan julkaista häpeälistalla tut.ot.om uutispalstalla (ellei tietosuojavaltuutettu tai yo-kunta puutu asiaan). Edelleen näkee jatkuvasti sekoilua käsitteiden luku (chapter), kohta (section) ja kappale (paragraph) kanssa. Oikeata ratkaisua siihen, kuinka paksu suunnitteludokumentin tulisi olla, ei ole. Opiskelijoita, jotka kyselevät tällaisia, pitäisi oikeastaan rangaista miinuspisteillä, koska he eivät ole sisäistäneet ohjelmistotuotannon "filosofiaa". Dokumentti on tietenkin niin paksu kuin on tarpeellista, eikä yhtään sen paksumpi ! ;-) Suunnitteluosaa tehdessänne viimeistään huomaatte, mitä olisi voinut tehdä toisinkin. Tai sitten teitte kaiken oikein. ;-) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Määrittelydokumentti on se, mitä myyntihenkilöt lupaavat. Suunnitteludokumentti on se, miten ohjelmisto pitäisi kasata. Valmis sovellus on se, mitä toteutuspuolen kaverit pystyivät koodaamaan. :-) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Älkää sekoilko tässä vaiheessa. Tarkoituksena on vain tarkentaa määrittelyvaiheen tuloksena syntyneitä tietoja suunnitteluvaiheen vaatimalle tasolle. Suunnitteluvaiheen tiedoista ei ole pitkäkään matka toteutukseen eli koodaukseen. Aivan uusiakin tietoja kyllä tarvitaan, kun havaitaan asioita joita ei ennen oltu huomattu. :-) Älkää kiinnittäkö huomiota dokumenttirungon ylimääräisiin loppulisäyksiin, jollei teillä ole aikaa. Tärkein asia on saada se dokumentti tehtyä. Muistakaa oikoluku ! Suunnittelun tavoite on ratkaista, miten määrittely ja sen vaatimukset toteutetaan. Luodaan erilaisia vaihtoehtoisia ratkaisumalleja, kehitellään ja vertaillaan niitä, käytetään hyväksi jo keksittyä ja olemassaolevaa tietoa. Projektiin sopimattomia muutoin hyviä ajatuksia ja ratkaisumalleja hylätään. Mikä olisi sopiva tarkkuus moduulien kuvauksissa ? Esimerkiksi kyseessä on merkkijonojen lajittelu aakkosjärjestykseen. Jollei ole erikoisia muita vaatimuksia (mm. vasteajat), voidaan moduulikuvauksessa vain todeta että käytetään Quicksort-algoritmiä tai Kuplalajittelua. Jos sen sijaan käytetÄän Ahto_Simakuutio_Special_Sort-algoritmiä, on sen toiminta syytä selostaa pseudokoodilla, tai jos tuo A_S_S_S on todella monimutkainen, niin kuvata koko lajittelualgoritmi suoraan ohjelmointikielellä. Yleisesti epämääräisiä sanontoja ei saa esiintyä missään kohtaa tekstissä. Toteuttajille ei saa aiheutua hämmennystä ja epäselvyyksiä suunnittelua lukiessaan. Koodausvaiheessa ei pitäisi syntyä ongelmia, miten jokin kohta tulisi koodata. Yleisesti asiahan on niin, että jollei jotakin seikkaa ole mainittu dokumentissa, niin kukin lukija tulkitsee sen niinkuin itse parhaaksensa kuvittelee (eli pieleen saattaa mennä). Suunnittelutavoitteita (jälleen eräs luettelo) ; - joustavuus - kannettavuus (portability) - siirrettävyys (transferability) - luotettavuus - tehokkuus - tukevuus (varmuus) - uudelleenkäyttö - ylläpidettävyys - ymmärrettävyys. Suunnittelussa yritetään sitten kuvata se MITEN asiat tehdään. Suunnitteluvaiheessa tehdään mm. - järjestelmän arkkitehtuurisuunnittelu (ohjelmamoduulitasolle) - kaikki rajapinnat määritetään tarkasti - tietokannan rakenteen suunnittelu (tietokantamäärittelyt). **************************************************** YLEISTÄ SUUNNITTELUDOKUMENTIN SISÄLLÖSTÄ; **************************************************** Pääasioita suunnittelun sisällössä ovat - toteuttajan näkökulma - ylemmän tason tekniset ratkaisut - ohjelmiston jako osiin - kaikille toteuttajille yhteisten asioiden kuvaukset - moduulien rajapinnat - moduulien toteutusratkaisut. Tärkeimmät asiat ovat: moduulien sisältö tarkasti selvitettynä, sekä käyttöliittymä ja tietokanta kiinnitettyinä (elleivät ne ole jo täysin valmiina määrittelyssä). Mikäli kaikki tiedot eivät ole selvillä ennen toteutuksen alkamista, tulee epätäydelliset kohdat selittää yksikäsitteisesti (ettei lukija luule asian olevan täysin kunnossa) Määrittelyssä on mahdollista jättää muutosvaraa määrityksiin. Kuitenkaan suunnittelussa asioita ei voi enää jättää avoimiksi; ohjelmoijan asia ei ole miettiä mihin jätetään muutosvaraa. Mikäli versiohistoriaa käytetään, sijaitsee se ennen varsinaista tekstiosuutta. Yleensä heti sisällysluettelon jälkeen. Sivunumeroinnissa olisi hyvä käyttää muotoa, jossa näkyisi dokumentin sivujen kokonaismäärä. Esimerkiksi: 2/13 tai 2(13). Joka sivulla olisi hyvä olla projektin tunniste ja dokumentin tai ohjelman versionumero tai päivämäärä, ettei myöhemmin tulisi sekaannuksia eri paperinippujen kanssa. Jos tuntuu hankalalta sisäistää, mitä suunnitteludokumenttiin oikeastaan pitäisi kirjoittaa, ajatelkaa vaikka niin, että saisitte tehtäväksi koodata ko. ohjelman. Millaisi tietoja tarvitsisitte - tehkää sellainen suunnitteludokumentti. Viittauksista; dokumentin ylläpidon kannalta on perusteltua kirjoittaa usein toistuva (pitkä) tekstikappale tai kuva vain ensimmäiseen esiintyvään paikkaan, ja muihin kohtiin viittaus siihen. Luettavuuden kannalta tämä ei sitten olekaan paras ratkaisu. Mikäli kysymys on lauseesta tai kahdesta, voi ne (lyhyitä pätkiä) kirjoittaa useampaankin paikkaan. Dokumentoinnin eräs periaate on välttää redundanssia eli sitä moninkertaista samaa tietoa eri kohdissa (nimenomaan sen ylläpidon takia). Suunnittelussa ei tulisi ilman hyviä perusteluja kiinnittää muuttujien nimiä, hakemistopolkuja, tiedostonimiä jne. Hyvä perustelu on firman koodaustyyliohje tai liityntä jo olemassaolevaan järjestelmään jolloin yhdenmukaisuus nimissä yms. on vaatimus. Sanaa "standardi" ei pidä viljellä puolihuolimattomasti, elleivät kyseessä olevan standardin nimi ja numero ole tiedossa. Paljon puhutaan "standardeista" puhekielessä, mutta kun asioita lähdetään tarkemmin tutkimaan ei kyseessä ole kuin jonkin firman tai tuotteen "vakiintunut käytäntö". ********************************************************************* SUUNNITTELUDOKUMENTTI SISÄLLYSLUETTELORUNKO TTKK/OHJ:n paljon mukailema ANSI/IEEE 1016-1987 (tekninen määrittely) ********************************************************************* (Software Design Descriptions, includes Architectural Design and Detailed Design.) --------------------------------------------------------------------- 1. JOHDANTO (Introduction) Antaa yleiskuvan suunnittelusta. 1.1 tarkoitus Dokumentin tarkoitus, miksi tehty ja mihin tarkoitukseen, kenelle (oman firman toteutusporukka vaiko alihankkija vai kuka) tarkoitettu. 1.2 tuote Tuotteen nimi, tarkoitus ja tavoitteet. 1.3 dokumentin kattavuus 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.4 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.5 viitteet Viittaukset muihin lähteisiin (dokumentit, standardit, käsikirjat). 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). 1.6 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ä. 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. 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. 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 Arkkitehtuurisuunnittelussa tehdään ylemmän tason suunnittelu, jaetaan ongelma osiin. Tässä kuvataan ohjelmiston arkkitehtuuri yleisellä tasolla: ylimmän kä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. Suunnittelutavoitteet sekä perusteet valitulle arkkitehtuurille eli miksi juuri tällainen arkkitehtuuri. 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, tiedostojenkä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 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 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. Ohjelmiston jako 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). Jokaisesta moduulista kuvataan sen tehtävä, liittymät muihin osiin sekä toteutusnäkökohdat. 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.x 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.x.1 yleiskuvaus - nimi 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.x.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.x.3 toteutus Ohjeita moduulisuunnittelua ja toteutusta varten; tyypillisesti toimintaa on hahmoteltu pseudokoodilla tai hankalat kohdat jopa ohjelmakoodilla. - 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.x.4. virhekäsittely - poikkeus- ja virhetilanteet Tärkeää on selvittää miten moduulin tulee reagoida eri virhetilanteisiin. Tässä kohtaa viimeistään määritellään virheilmoitustekstien tarkka sisältö ja sanamuoto (jollei ole jo määrittelyssä), sekä ohjelman toiminta virheen jälkeen. Myös havaitut/oletetut virhetilanteet kannattaa rehellisyyden ja dokumentin käytettävyyden nimissä kirjata. Mm. testaussuunnitelmaa tehtä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 kirjata perusteluineen johonkin sopivaan lukuun tai kohtaan. Seuraava dokumentin lukija näkee, että tuotakin on mietitty. Samoin jos te itse sattumoisin lukisitte omaa dokumenttianne puolen vuoden päästä, ette varmaankaan muistaisi mitä asioita on sitä tehtäessä mietitty. 7. VIRHEKÄSITTELY (ellei selostettu täydellisesti 4. luvussa) - 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. 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. < ja seuraavista asioista lisälukuja tarpeen mukaan... > Ylläpito Testattavuus Jäljitettävyys Siirrettävyys Turvallisuus Luotettavuus Ratkaisun rajoitteet Käyttöliittymä (jos ei tarkasti määrittelyssä) Tietokanta (jos ei tarkasti määrittelyssä tai kohdassa 3.2) --- dokumentin sisällysluettelon selostus loppuu tähän --- SUUNNITTELUUN LIITTYVÄÄ YLIMÄÄRÄISTÄ ASIAA --------------------------------------- Olio-ohjelmoinnissa luokan kuvaus esim: NAME: CLASS: SCOPE: DESCRIPTION: PARAMETERS: RETURN VALUE: CALLED FUNCTIONS: USED DATA MEMBERS: IMPLEMENTATION: --------------------------------------- MODUULIKUVAUS (PAKKAUSKUVAUS) - johdanto - moduulin toiminta - moduulin rakenne - moduulin rajapinnat - sisäiset moduulit - poikkeus- ja virhetilanteet - yleistä moduulin testauksesta. Moduulikuvauksissa on tyypillisesti selostettu moduulin sisäinen toiminta pseudokoodilla. No aivan yksinkertaisissa kohdissa tuota ei tarvita, ja toisaalta taas hyvin tärkeät ja/tai monimutkaiset kohdat (vasteaikavaatimukset, muistitilavaatimukset tms.) voi olla syytä kirjoittaa oikein ohjelmakoodina (jos on epäilys ettei toteutusporukka osaa/tiedä/keksi sitä "oikeaa" ratkaisutapaa). Pseudokoodihan on varmaan tuttu juttu kaikille ohjelmoinnin peruskursseilta. Se on "vapaamuotoista" yleensä englanninkielen tai suomen kielen ja ohjelmointikielen sekoitusta. Tarkoituksena on selkeätajuisesti kuvata moduulin toiminta. Esimerkkinä voisi olla vaikka: MODULE: MENNAKO_SYOMAAN_VAI_EI if painettu_nalka_nappia then lue_tutki_ruokajonoa if ruokajono >= 10 then tulosta pitka_ruokajono ilmoita ei_kannata_menna_jonottamaan else tulosta lyhyt_ruokajono ilmoita syomaan_vaan_nopeasti palaa valmiustilaan. YLEISTÄ MODUULISTA - moduulin tehtävä - yleiskuvaus moduulin toimintaperiaatteista - liittymät muihin osajärjestelmiin/moduuleihin - erityiset suunnitteluperusteet/algoritmit - sivuvaikutukset - moduulin aktivointi - mikä aktivoi - milloin aktivoi - miten aktivoi - syötteet - tulosteet - virhetilanteet/virheistä toipuminen - suojausnäkökohdat - varmuus/turvallisuusnäkökohdat - ylläpidettävyysnäkökohdat - joustavuusnäkökohdat - tilavaatimukset - varus-, yleis- ja erikoisohjelmien kÄyttö. MODUULIN RAJAPINTA - moduulin nimi - moduulin tarkoitus/tehtävä * moduulin tyyppi (esim. pääohjelma, funktio, aliohjelma, pakkaus, luokka, prosessi) * kuka/mikä aktivoi ja miten (***** kutsumiset siis... ******) - operaatiot/palvelut (vain jos on luokkia) - saapuvat ja lähtevät sanomat (vain jos on olioita) - parametrit - nimi - moodi (IN, OUT, INOUT) - tyyppi - tarkoitus - mahdolliset arvot - pakollisuus - poikkeukset/paluuarvot - käyttörajoitukset * suorituskyky-, luotettavuus-, varmuus-, joustavuus-, ylläpidettävyys- yms. vaatimusten huomioiminen - varoitukset, sivuvaikutukset * liittymät muihin moduuleihin * laitteistoliittymät * varus- ja/tai valmisohjelmistojen hyödyntäminen - muut vaadittavat komponentit/moduulit/aliohjelmat * tietorakenteet (näkyvät) - huomautukset. MODUULIN TOTEUTUS - tietorakenteet (tarvittaessa kuva) - algoritmit - pseudokoodi - virhe- ja poikkeustilanteet - mihin tilanteisiin varaudutaan - miten toimitaan, kun tilanne kohdataan - mistä tilanteista yritetään toipua ja miten - kerätäänkö virhetilastoa - muuta tarpeellista, esim. rakennekaavio. Luotettavuus (robustisuus, robustness) tarkoittaa ohjelman kykyä täyttää asiakkaan/määritysten vaatimukset. Esim. jos sähkökatkoksen takia ohjelma sekoaa ja asiakkaiden luottotietoja hukkuu vain enintään 8 %, niin onko se hyväksyttävä menetys... ei taida olla kovin luotettava ohjelma... tai jos teho-osaston valvontaohjelma sekoilee, kun syötteitä alkaakin tulla 15 anturilta vauhdilla 10 tietoa sekunnissa... ?