Pieni tyyliohje aloittelevalle Java-ohjelmoijalle

Tämä sivu esittelee joitakin tapoja ulkoasultaan selkeiden Java-ohjelmien kirjoittamiseen.

Inspiraation lähteinä olen käyttänyt omaa kurssimateriaaliani, Sun-yhtion alkuperäisten Javan API-kuvausten ja muunkin dokumentaation tyyliä sekä Jari Juslinin erinomaista tyyliopasta.

Tätä ohjetta ei ole tarkoitettu kattavaksi tai sitovaksi. Ennemminkin kyseessä on esimerkki, jonka avulla voi rakennella oman selkeän tyylinsä. Joistakin kohdista voi olla perustellusti eri mieltä. Tavoitteesta ei. Se on se selkeä tyyli.

Sisältö:

• Miksi ohjelmien pitää olla selkeitä
• Kommentoinnista
• Nimiä muuttujille, metodeille, vakiolle ja luokille
• Alirakenteet ja ohjelmatekstin sisentäminen
• Tulostuslauseiden ulkoasusta
• Parametreista
• Javadoc- kommentonnista

Miksi ohjelmien pitää olla selkeitä

Tuhatrivinen ohjelma on vielä aika pieni, mutta jo sellaisen hahmottaminen on mahdotonta, jos ohjelmoija ei ole kirjoittanut ohjelmaansa selkeäksi. Jopa muutaman rivin mittainen "mikroskooppisen pieni" ohjelma on hyvin vaikeasti ymmärrettävissä, ellei ymmärtämistä auteta ulkoasun selkeydellä.

Mitä seuraava ohjelma tekee?

public class ABC{public static 
void main(String[] args){double x,y;System.out.println
("Anna kaksi lukua!");x 
= Lue.dluku();y = Lue.dluku();if (x 
> y)System.out.println("Ensimmäinen luku on suurempi."
);else if (x < y)System.out.println(
"Toinen luku on suurempi.");else 
System.out.println("Luvut ovat yhtä suuret.");}}

public class KumpiSuurempi { /* ilmoittaa kumpi kahdesta syöttöluvusta 
                                 on suurempi                           */

  public static void main(String[] args) {
    double luku1, luku2;

    System.out.println("Anna kaksi lukua!");
    luku1 = Lue.dluku();
    luku2 = Lue.dluku();

    if (luku1 > luku2)
      System.out.println("Ensimmäinen luku on suurempi.");
    else if (luku1 < luku2)
      System.out.println("Toinen luku on suurempi.");
    else
      System.out.println("Luvut ovat yhtä suuret.");
   }
}

Kommentoinnista

/*************************************************************************
*   Sovellus kahden luvun summan laskentaan, tekijä Olli Opiskelija
*  
*   muutettu viimeksi 26.1.1999 
**************************************************************************/



/////////////////////////////////////////////////////////////////////////////
// 
//  Formula 1 -simulaattorin pääohjelmaluokka, versio 12.B.36a (26.1.1999)
//
//  Copyright 1999 Orvokki Ohjelmoija
//                 Oy Simulaattori Ab
//
/////////////////////////////////////////////////////////////////////////////

Jos luokasta on tarkoitus luoda ilmentymiä, sen alkuun on syytä kirjoittaa lyhyt ja selkeä selostus luokan käyttötavasta. Myös metodien toteutuksen yhteydessä on hyvä mainita metodin tehtävä:

//--------------------------------------------------------------------
// Luokka KuuLaskuri toteuttaa laskurin, joka laskee kuukausien 
// numeroita 1, 2, ..., 11, 12, 1, 2, 3, ....
//
// Konstruktori:
//
//       public KuuLaskuri()  luo KuuLaskuri-olion, jonka kuukauden 
//                            numero on 1
//
// Julkiset metodit:
//
//    public int moneskoKuu()    palauttaa arvonaan KuuLaskuri-olion
//                               tietämän kuukauden numeron
//
//    public void seuraavaKuu()  edistää KuuLaskuri-olion kuukautta
//                               yhdellä
//--------------------------------------------------------------------
public class KuuLaskuri {

  private int kuu;   // sallitut arvot 1,..12

  // ----- konstruktori: -------

  public KuuLaskuri() { // luo KuuLaskuri-olion, jonka kuukauden
     kuu = 1;            // numero on 1
   }

  // ----- julkiset metodit: -----------

  public int moneskoKuu() {  // palauttaa arvonaan KuuLaskuri-olion
    return kuu;              // tietämän kuukauden numeron 
  }

  public void seuraavaKuu() { // edistää KuuLaskuri-olion kuukautta
    ++kuu;                    // yhdellä
    if (kuu == 13)
      kuu = 1;
  }

}

     i = i + 1; // add one to i

Mutta joissakin erikoistapauksissa yksittäisen lauseen kommentointikin voi olla hyödyllistä. Jos tekee jotakin kovin nokkelaa kommentti voi olla tarpeen - yleensä kuitenkin kannattaa suosia selkeyttä nokkeluuden kustannuksella.

Yksi erikoistapaus, jossa kommentointi on tärkeää, on metodin suorituksen lopettaminen jossakin muualla kuin lopussa:

  private static int hae(int[] taulu, int haettava) {

    for (int i=0; i<taulu.length; ++i) 
      if (taulu[i] == haettava)
        return i; // tärppäsi, lopetetaan

    return -1; // päästiin loppuun eikä löytynyt
  }

Nimiä muuttujille, metodeille, vakiolle ja luokille

Javassa on tapana antaa muuttujalle ja metodille nimi, joka alkaa pienellä kirjaimella. Luokkien nimet aloitetaan isolla kirjaimella ja nimetyt vakiot kirjoitetaan kokonaan isoilla kirjaimilla. Näin nimestä näkee heti, mistä on kyse. Tätä tapaa on syytä noudattaa!

public class Luokka {

   public void metodi(int parametri) {
     final int VAKIO = 42;
     int muuttuja;
 ....

  int ensimmäinenSyöttöluku, kissojenLukumäärä;

Jotkut suosivat alaviivaa:

  int ensimmäinen_syöttöluku, kissojen_lukumäärä;

    for (int i=0; i<taulu.length-1; ++i) 
      for (int j=i+1; j<taulu.length; ++i)
        if (taulu[i] > taulu[j]) {
          int apu  = taulu[i];
          taulu[i] = taulu[j];
          taulu[j] = apu;
        }

Alirakenteet ja ohjelmatekstin sisentäminen

Javan luokka sisältää kenttiä, konstruktoreita ja metodeita. Kentän määrittely voi sisältää alkuarvojen asetuksia, metodit sisältävät muuttujien määrittelyitä ja muita lauseita, joista muodostuu metodin algoritmi.

Algoritmit sisältävät alialgoritmeja: while-lause voi toistaa if-lausetta, jonka else-osassa on toistolause, joka toistaa toistolausetta, joka sisältää if-lauseen, jne.

Ohjelman looginen rakenteisuus on syytä esittää ohjelman ulkoasun rakenteisuutena, jotta silmä voisi hahmottaa, mistä on kyse. Tapana on sisentää alirakenne:

public class Luokka {

   private int kissa = 7;

   public void hiiri() {
      int kärpänen;
      while (ulkonaTuulee())
         if (luntakinSataa())
            teeSitäSunTätä();
         else {
            teekinTota();
            jaTätäKans(); 
         }
      alaVähitellenLopetella();
   }
}

Jotkut suosivat toisiaan vastaavien aaltosulkeiden kirjoittamista samalle sarakkeelle ja omalle rivilleen:

public class Luokka 
{
   private int kissa = 7;

   public void hiiri() 
   {
      int kärpänen;
      while (ulkonaTuulee()) 
         if (luntakinSataa()) 
            teeSitäSunTätä();
         else 
         {
            teekinTota();
            jaTätäKans();
         }
      alaVähitellenLopetella();
   }
}

Tulostuslauseiden ulkoasusta

System.out.println("***************************************\n" +
                   "*        Tosi Hieno Ohjelma           *\n" +
                   "*        ------------------           *\n" +
                   "*                                     *\n" +
                   "*  komennot ovat : y, a, w, p         *\n" +
                   "***************************************\n" );

Parametreista

  public String yksiMetoVaan( int kissa,
                              String hiiri,
                              PikkuVarasto koira,
                              BufferedReader hevonen) {
    ...

Javadoc-kommentoinnista

Ns. dokumenttikommentti esitetään merkkiyhdistelmien /** ja */ välissä. Järjestelmä sisältää myös monia muita ilmauksia dokumentaation ohjaamiseen.

Luokka KuuLaskuri voitaisiin kirjoittaa muotoon:

/** Luokka KuuLaskuri toteuttaa laskurin, joka laskee kuukausien 
    numeroita 1, 2, ..., 11, 12, 1, 2, 3, ....
*/
public class KuuLaskuri {

   private int kuu;   // sallitut arvot 1,..12

   // ----- konstruktori: -------
   /**  luo KuuLaskuri-olion, jonka kuukauden
        numero on 1
   */ 
   public KuuLaskuri() {
     kuu = 1;
   }

  // ----- aksessorit: -----------

  /** palauttaa arvonaan KuuLaskuri-olion
      tietämän kuukauden numeron
  */
  public int moneskoKuu() {
    return kuu;
  }

  /** edistää KuuLaskuri-olion kuukautta
      yhdellä
  */
  public void seuraavaKuu() {
    ++kuu;
    if (kuu == 13)
      kuu = 1;
  }
}

Javadoc esitellään perusteellisesti Sun-yhtiön sivulla How to Write Doc Comments for Javadoc.

...