Luin Robert C. Martinin mainion kirjan Clean Code ja sain ahaa-elämyksen. Martin vertaa koodin rakennetta kirjoitettuun teokseen: hyvää sovelluskoodia voi lukea kuin kertomusta. Kirjan ja ohjelmakoodin rakenteille löytyy muitakin yhtäläisyyksiä.
Erityisesti tietokirjassa sisällysluettelo on tärkeä osa kirjaa. Lukijan on löydettävä haluamansa tieto nopeasti, joten hakemisto ei saa olla liian laaja. Valtava sisällysluettelo kertoo myös siitä, että käsiteltävä aihe on liian laaja ja hajanainen. Kirja kannattaisi ehkä jakaa useampaan osaan tai materiaalia riittäisi jopa kirjasarjaksi.
Luokan julkiset metodit muodostavat luokan sisällysluettelon. Pitkä sisällysluettelo tässäkin tapauksessa antaa aihetta miettiä kokonaisuuden jakamista useaan osaan, moneksi luokaksi.
Kirjan luku käsittelee yhtä asiaa, kuten metodikin tekee. Jos halutaan tarkentaa, aloitetaan uusi alaluku tai koodataan uusi privaatti funktio. Julkisen metodin sisältönä on kutsuja luokan sisäisiin metodeihin, kertomuksen alalukuihin.
Kirja-analogian kautta on myös itsestään selvää, että metodin lauseiden on oltava samalla abstraktiotasolla. Eihän sisällysluetteloa ja sisältöä voi sotkea samaan kappaleeseen.
Hyvässä koodissa metodin nimestä on pääteltävissä sen toiminta koodia katsomatta, kuten kirjan sisällysluettelon otsikosta on pääteltävissä kappaleen sisältö. Metodi suorittaa nimensä mukaista toimintaa eikä mitään muuta.
Tämän ohjeen noudattamisen olen huomannut vaativan hivenen kurinalaisuutta - mielelläänhän sitä ymppäisi olemassa olevaan metodiin lisää toiminnallisuutta vaivautumatta pohtimaan uutta nimeä. Jos nimeäminen alkaa tuottaa vaikeuksia ja nimen pituus kasvaa kohtuuttomaksi, on aika pilkkoa metodin koodi moneksi metodiksi.
Usein kun sovellukseen tulee lisää toiminnallisuuksia, luokan koko alkaa vähitellen paisua ja alkaa muodostua erillisiä asiakokonaisuuksia. Kannattaakin jakaa luokka useaksi luokaksi, kuten kirjassa hajanainen tai liian pitkäksi venyvä kappale. Lukijan on helpompi seurata tarinaa, kun kaikkea ei kirjoitettu yhteen pötköön. Varsinkin jos sisältö on hyvin asiapitoista, kuten ohjelmakoodissa tuppaa olemaan.
Jos kirjassa on havaittavissa paljon viittauksia muihin kirjan lukuihin, on syytä miettiä, mahtaako kappalerakenteessa olla jotain vialla. Kirjan kappaleet pitää ehkä jäsentää eri tavalla, jotta niiden välillä ei olisi niin paljon riippuvuuksia ja lukija selviäisi ilman sivujen edestakaista pläräämistä.
Ohjelmakoodissa käytetään termiä piirrekateus, jos luokan metodit ovat kiinnostuneempia muiden luokkien muuttujista ja funktioista kuin niistä, joita omasta luokasta löytyy. Piirrekateudesta pääsee eroon miettimällä luokkien rakenne uudelleen ja sijoittamalla yhtä aikaa tilaansa muuttavat asiat samaan luokkaan.
On ymmärrettävää, että kirjassa ei kerrota samaa asiaa moneen kertaan, vaan viitataan sivulle, jossa asia on käsitelty. Kirjan rakenne pysyy napakkana ja selkeälukuisena, eikä korjatussa painoksessa silloin tarvitse muistaa tehdä samaa korjausta monelle sivulle. Sovelluskoodin monistaminen on pannassa samoista syistä.
Kirjaa sen paremmin kuin koodiakaan ei kirjoiteta itselle vaan toisille lukijoille. Jos haluat omalle koodillesi tyytyväisen ja laajan lukijakunnan, kannattaa panostaa paitsi sisältöön, myös selkeään rakenteeseen.