Dokumentaatio, osa 1 Tehtävämäärittely Kirjoitetaan lyhyt kuvaus toteutettavasta ohjelmasta. Kuvaus tarkentuu myöhemmin, aluksi dokumentoidaan vain ideat, joiden pohjalta työtä lähdetään tekemään. Kuvaus sisältää muutaman tekstikappaleen pituisen yleiskuvauksen, tyyliin: aihe: ilmoittautumisjärjestelmä Toteutetaan järjestelmä, jonka avulla ylläpidetään tietojenkäsittelylaitoksen kurssitietoja sekä tietoja kursseille ilmoittautuneista opiskelijoista... Tämän lisäksi listataan ranskalaisin viivoin järjestelmän tarjoama toiminnallisuus: käyttäjät: opiskelija ja opetushallinto opiskelijan toiminnot: onnistuu jos salasana ja käyttäjätunnus oikein kaikkien kurssien listaus ilmoittautuminen onnistuu jos kurssi ei ole täynnä ja opiskelija ei ole jo kurssilla omien ilmoittautumisten listaus opetushallinnon toiminnot: onnistuu jos salasana ja käyttäjätunnus oikein uusien kurssien lisäys tietyn kurssin ilmoittautujien listaaminen... Koska molemmilla käyttäjillä on samoja toimintoja, ne kannattaa yhdistää: kaikkien käyttäjien toiminnot:... Kuvauksen ei tarvitse olla kovin pitkä eikä kattava. Kuva siitä, mitä ohjelmistolta halutaan, tulee tarkentumaan koko ajan toteutuksen edetessä. Tämä on osa ketterän kehityksen ideaa! Dokumentaatio, osa 2 Javadoc
Ohjelmakoodi kommentoidaan Javadoc:in avulla. Ks. esim. http://en.wikipedia.org/wiki/javadoc ja http://java.sun.com/j2se/javadoc/writingdoccomments/ Tarkemmat ohjeet JavaDocin käyttöön Ohjelman rakenteen kuvaaminen Ohjelman/suunnitelman rakenne tullaan kuvaamaan tarpeellisella tasolla. Kuvauksessa tulee olla luokkarakenne hahmotelma ydintoiminnallisuuksista käyttöliittymän näkymien välinen navigaatiorakenne Kaksi edellistä esitetään "tuopinalustaan piirrettynä miniuml:na", käyttäliittymän navigaatiorakenne vapaamuotoisena mutta selkeänä kuvan ja tekstin sekoituksena. Koska ohjelman rakenne kasvaa ja muuttuu ajan myötä, käy samoin ohjelman rakenteen kuvaukselle. Tämän takia rakenne hahmotellaan käsin lappusille. Ohjelman lopulliseen dokumentaatioon tehdään luokkarakenteen kuvaus jollakin piirto-ohjelmalla tai käsin. Seuraavassa käydään läpi muutama UML:n perusrakenne, jotka riittävät harjoitustyön dokumentoinnin tarpeisiin. miniuml: Luokkarakenteen kuvaaminen viikko 1: Luokka kuvataan laatikkona jossa on kolme osaa: luokan nimi attribuutit konstruktorit metodit Koska Javadoc kuvaa attribuutit ja metodien nimet, kannattaa useimmiten ne jättää merkitsemättä luokkarakenteen kuvauksessa ja kuvata luokat pelkkinä laatikkoina joissa on luokan nimi. Muutaman toiminnallisuuden kannalta oleellisen metodin voi toki luokkalaatikkoon merkitä. Ensimmäisellä viikolla meille riittää hyvin yksinkertainen luokkarakenteen kuvaus. Jokaisesta luokasta tulee oma laatikko, ja jos luokkien tai luokkien mukaisten olioiden välillä on yhteys, tulee laatikoiden välille viiva. Viivalle voi merkitä mitä yhteys tarkoittaa. Seuraavassa esimerkkinä Ilmo-järjestelmän hyvin yksinkertainen kuvaus. Oletetaan nyt, että opiskelijoita edustaa oma luokka Opiskelija.
viikko 2: Tarkennamme edellisellä viikolla aloitettua ilmo-järjestelmän luokkakaaviota. Huomaamme, että edellisen viikon kuvaan piirretyt yhteydet eivät vastaa täysin koodissa olevia yhteyksiä. Koodissa nimittäin Ilmo-luokan olio ei tunne Käyttäjatietokanta-oliota, siispä niiden välille ei tule yhteyttä. Alla on tarkennettu kuva. Yhteyksiin on nyt lisätty suuntia ja osallistumisrajoitteita.
miniuml: Toiminnallisuuden kuvaaminen Ei riitä, että kuvaamme luokkarakenteen. Luokkarakenteesta ei nimittäin käy millään lailla ilmi miten ohjelman toiminnallisuus on toteutettu. Toiminnallisuudella tarkoitetaan suurinpiirten samaa kuin yllä tehtävämäärittelyssä listattuja ohjelman tarjoamia toimintoja, esimerkiksi ilmottautumisjärjestelmässä kurssille ilmoittautuminen ohjelman alustustoimet Ohjelma toteuttaa toiminnallisuutensa olioidensa välisen yhteistyön avulla. Eri oliot kutsuvat toistensa metodeja siten, että haluttu toiminto saadaan aikaan. Toiminnallisuutta voidaan kuvata UML:n sekvenssikaavion avulla, ks. ohjelmistojen mallintamisen materiaali. Sekvenssikaavioilla kannatta kuvata vain ohjelman tärkeimmät toiminnalisuudet.
Toiminnallisuuden nopea luonnostelu sekvenssikaavioina ennen ohjelmointia on erittäin hyödyllistä, näin voin nopeasti kartoittaa mitä osia toiminnallisuudesta kannattaa laittaa minkäkin olion vastuulle. Miten ja milloin rakennetta ja toiminnallisuutta tulee kuvata? Luokkarakenteen ja toiminnallisuuden kuvaamisen ja ohjelmoinnin tulee edetä käsi kädessä. Ensin suunnitellaan hieman ohjelman rakennetta ja toiminnallisuutta piirtelemällä luonnoksia tuopinalustoille. Sen jälkeen ohjelmoidaan suunnilleen suunnitelman mukaan. Yleensä kuitenkin käy niin, että ohjelmoidessa huomataan, että tuopinalustaan piirretyt suunnitelmat eivät ole kaikin osin järkeviä ja ohjelmoitu toteutus onkin hiukan erilainen. Se ei haittaa. Kun taas suunnitellaan ohjelmaa hiukan pidemmälle, otetaan uusi tuopinalusta ja lähtökohdaksi otetaan toteutuksen nykytilanteen mukainen ohjelman rakenne. Tuopinalustoille ja suttupapereille suunnittelu ja ohjelmointi siis etenevät iteratiivisessa ohjelmiston toteuttamistavassa käsi kädessä. Kun ohjelma on valmis, voi ohjelman rakennetta ja toiminnallisuutta kuvata tarvittaessa tarkemmin, piirto-ohjelmalla tai UML-editorilla piirrettävin kuvin. Liian tarkka kuvaaminen esimerkiksi luokkien suhteen ei ole tarpeen jos ohjelmasta tehty Javadoc ajaa saman asian. Käyttöohje Lopussa kirjoitetaan ohjelmalle lyhyt käyttöohje. Mieti käyttäjää, joka ei tiedä mitään ohjelmastasi!