1. COMP.CS.140
  2. 10. Työnjako ja tiimityöskentely
  3. 10.2 Dokumentointi ja konventiot

Dokumentointi ja konventiot

Ohjelman dokumentointi on tärkeä, mutta herkästi sivuun jäävä osa ohjelmiston kehitystä. Siksi senkin osalta on suunta käytäntöihin, jotka tuottavat riittävän dokumentaation luontevasti osana toteutustyötä.

Ohjelman dokumentointi

Ohjelman dokumentaatio voi olla erillinen ohjelmakoodin mukana tuleva tai ohjelmakoodissa itsessään oleva kuvaus siitä, miten ohjelma toimii, miten se on toteutettu ja miten sitä tulisi käyttää. Ohjelman kehittäjille dokumentaatiosta tulisi käydä ilmi vähintään seuraavat asiat:

  1. Ohjelman toiminnalliset vaatimukset eli spesifikaatio

  2. Ohjelman kokonaisarkkitehtuuri

  3. Koodin dokumentointi: rajapinnat, kooditason kommentit

  4. Toteutushistoria: tätä varten yleensä on olemassa projektille versionhallinnan loki

  5. Käyttöohje

  6. …

Dokumentaatiolla on aina kohderyhmä. Dokumentit voivat olla projektin sisäisiä tai tarkoitettu projektin ulkopuolisille. Hyvä dokumentaatio huomioi kohderyhmän ja samalla on kohderyhmästä riippumatta:

  • selkeä

  • lyhyt

  • kattava

  • sisältää kaiken tarpeellisen tiedon

  • ei sisällä mitään turhaa

Toimiva ohjelmisto ohittaa kattavan dokumentaation

Ketterässä ohjelmistokehityksessä agile manifestosta alkaen korostaa ohjelmiston tärkeyttä dokumentaation kustannuksella. Tämä ei kuitenkaan tarkoita sitä, että dokumentointi olisi turhaa. Painotus kuitenkin on, että dokumentoidaan vain eri sidosryhmien kannalta olennaiset asiat ja unohdetaan dokumentointi dokumentoinnin vuoksi.

Ohjelmistoprojektin dokumentaatio koostuu usein joukosta erilaisia datalähteitä. Dokumentaatioksi lasketaan esim.:

  • luokkakaavio

  • README

  • Muutosloki

  • Rajapintadokumentaatio

  • Versionhallinan lokit

  • Käyttöohje

Miten koodia kommentoidaan

Sinulle on aiemmin opetettu, että koodia kuuluu kommentoida. Tämä pätee pienille ohjelmille. Suurien ohjelmien kohdalla itse ohjelmakoodia ei pidä kommentoida vaan kommentointi keskitetään rajapintojen dokumentointiin koodikommenttimuotoisina. Syy koodin kommentoimisen jättämiselle minimiin on yksinkertainen: koodin kuuluu olla muuten niin selkeää, ettei se tarvitse erillistä selitystä. Lisäksi jokainen kommenttirivi on myös rivi koodissa, joka pitää refaktoroinnissa muistaa päivittää vastaamaan uudistettua koodia. Kooditasolla kommentteja käytetäänkin vain tilanteissa, joissa on tehty jokin toteutusratkaisu, jota tulee selittää tai perustella. Otetaan esimerkki perustelemaan kommentoinnin painopisteen muutos:

/* if allocation flag is zero */
if ( alloc_flag.equals( 0 ) )
// Kommentin tarjoama lisäselkeys on olematon eli kommentti hyödytön
// The comment does not give any additional information that is not already evident in the code

/* if allocating new member */
if ( alloc_flag.equals ( 0 ) )
// Kommentti selkeyttää koodin tarkoitusta. Taikanumero 0 kuitenkin vain selkeyttä haittaava.
// The comment clarifies the purpose of the code. Magic number 0 still just obfuscates the code

/* if allocating new member */ //<- no need for the comment with good naming conventions in code
if ( alloc_flag == NEW_MEMBER )

Muita konventioita

Tiimin kesken on tärkeää sekä sopia työnjaosta että seurata sitä. Yksikertaiset menetelmät ovat yleensä parhaita. Esimerksi ns. Kanban-taulu auttaa seuraamaan ja priorisoimaan tehtävää koodaustyötä. Lisäksi sen avulla seurataan työn etenemistä. Kanban-taulu on käytännössä post-it-lappuja valkotaululla siten, että jokainen lappu kuvaa yhtä koodaustehtävää. Lappu etenee taululla vaiheesta toiseen siirtymällä sarakkeelta toiselle. Tyypillisiä sarakkeita ovat: backlog, toteutuksessa, jumissa ja valmis, mutta tiimi saa suunnitella taulunsa vapaasti. Helppo ja ilmainen työkalu taulujen toteuttamiseen on Trello.

Koodikonventioioden tehtävänä on pitää huolta siitä, että jokainen tiimin jäsen kirjoittaa yhdenmukaista koodia. Tämä parantaa koodin luettavuutta ja laatua sekä pitää koko projektin koodin yhtenäisenä. Sovittavia asioita ovat mm.:

  • Kommentointi (ml. Rajapintadokumentointi JavaDoc)

  • Sisennys: aina sisennä välilyönneillä. IDEt on mahdollista konfiguroida käyttämään järkevää välilyöntisisennystä tabulaattoria painettaessa (tai ne tekevät näin automaattisesti).

  • Rivin pituus: koodi on yleensä lyhyttä, joten kohtuullista rivin pituutta on perusteltua suosia. Klassinen mitta on 79 merkkiä.

  • Nimeäminen: koodi on hyvä kirjoittaa yhtenäisellä kielivalinnalla ja sopia yhdenmukainen tapa nimetä funktiot, muuttujat, vakiot jne.

  • Koodauskäytännöt ja -periaatteet, peukkusäännöt: esimerkiksi kantaluokan toteutuksia muuttavat aliluokan metodit merkitään @Override tai että kiinniotettaville poikkeuksille tehdään aina jotain.

  • Muut tyyliasiat: aaltosulkujen sijoittaminen, välilyöntien ja tyhjien rivien käyttö, annotaatioiden käyttö jne.

Esimerkki tyyliohjeesta Javalle on Google Java Style Guide.

Koodin katselmointi eli koodin laadun parantaminen koodia lukemalla läpi miettien:

  • Tekeekö se sitä, mitä pitää,

  • Vastaako se sovittuja koodikonventioita

  • Sisältääkö se toiminnallisia virheitä.

on toimiva tapa saada koodista kiinni vaikeasti muulla tavoin havaittavia ongelmia ja vikoja. Sujuvin tapa totetuttaa katselmointia on liittää se versionhallinnan käytön toimintatapoihin siten, ettei main-haaraan liitetä koodia suoraan vaan aina erillisen pyynnön (pull/merge requestin) kautta. Versionhallintaan liittyy myös joukko muita työskentelysopimuksia eli ainakin:

  • miten käytetään haaroja

  • miten ohjelmaa testataan

  • milloin ja kuka voi viedä tuotantoon

  • mitä kaikkea commit-viesteihin liitetään mukaan

Palautusta lähetetään...