Java-tyyliopas

Moduulitiedoston (.java) rakenne:

Alkuun kirjoitetaan paketin nimi, jolla määritellään mihin pakettiin moduuli kuuluu. Seuraavaksi annetaan luettelo käytetyistä muista paketeista ja lopuksi varsinainen koodi (luokat ja rajapinnat).

Moduulien pääluokka määritellään julkiseksi ja sen nimi määrää fyysisen tiedostonimen. Koodi kommentoidaan jo tekovaiheessa.

Tuotteen dokumentointiin käytetään Javadoc-HTML- generaattoria, joka luo Java- lähdekooditiedostoista dokumentaatiotiedostoja. Javadoc-ohjelmalle tarkoitettujen kommenttien täytyy alkaa merkeillä /** ja loppua merkkiyhdistelmään */.

Luokan määrittely aloitetaan Javadoc-kommenttilohkolla. Luokkakommenttien on alettava ensimmäisestä sarakkeesta, koska niiden on oltava Javadoc- ohjelmalle soveltuvia. Kommentointikielenä käytetään suomea. Seuraavassa Javadoc-ohjelmalle tarkoitettu kommenttilohko.

/**
* [Through Description of class]
*
* Recent Changes:
*     [date of important change - xx/xx/xx][who changed]
*         [BRIEF Description of change]
*
* @see [full-]classname[#method-name] [(can have zero or more of these)]
*
* @author [Author List on one line]
*/
public class className  
{           
    // class variables here
    // constructors here
    // additional methods here
}

Kommenttilohkon jälkeen luokan sisällä määritellään ensin muuttujat. Luokkamuuttujien jälkeen esitellään konstruktorit (ensin yksityiset, sitten julkiset). Muut metodit kirjoitetaan aakkosjärjestyksessä.

Pakettien nimet kirjoitetaan pienin kirjaimin.

Luokille, metodeille ja muuttujille annetaan merkitykselliset nimet. Jos nimi muodostuu useista sanoista, muiden kuin ensimmäisen sanan ensimmäinen kirjain kirjoitetaan isolla. Luokkien nimissä myös alkukirjain kirjoitetaan isolla. Alaviivoja ei suositella käytettäviksi luokkien, metodien tai muuttujien nimissä.

Jos käytetään 'final static' tyyppisiä vakioita , niiden nimet kirjoitetaan isoin kirjaimin ja sanat erotetaan alaviivalla (‘_’).

Jatkorivit ja sisennykset

Rivin pituus on korkeintaan 79 merkkiä. Jatkorivejä voi käyttää. Sisennykset tehdään neljän välilyönnin askelin. Alkava aaltosulku sijoitetaan rivin loppuun. Ensimmäisen tason lauseet (muuttujat ja metodien otsikot) sisennetään yhden sisennyksen verran. Metodien koodirivit sisennetään kahden tai useamman sisennyksen verran.

Muuttujien kommentointi

Jokainen käytetty muuttuja, jonka merkitys ei täysin selviä nimestä, on syytä kommentoida.

Yksityiset muuttujat kommentoidaan //-kommentilla samalla rivillä.

Julkiset muuttujat sisällytetään HTML-dokumentaatioon. Kommenttien on oltava Javadoc-ohjelmalle soveltuvia. Muista että kirjoitat dokumenttia, virkkeet loppuvat pisteisiin jne.

Esimerkki:

public class AClass 
{
    private int rows = 25;          // rows in rectangle
    private int cols = 80;          // column in rectangle

    /**
    * Value of x-coordinate
    */
    public int x;

    /**
    * Value of y-coordinate
    */
    public int y;
        ...
}

Metodien kommentointi

Jokaisen metodin alussa on kommenttilohko. Tässä lohkossa käytetään Javadoc-standardia, ja sen tarkoitus on kuvata metodi ja sen toiminnot.

Huomaa, että Javadoc-tageja voi esiintyä useita. Esimerkiksi @param-rivin pitää olla jokaiselle parametrille erikseen.

Seuraavassa on annettu esimerkki metodikommentoinnista.

// Class comment here (see above)
public class ClassName  
{   

    /**
    * [Brief ONE LINE description of method]
    * [Continuation of description above giving parameter specs, side 
    *  effects, etc.  Can be omitted if the first line says it all.]
    *
    * @param [pramName1] [description]
       ...
    * @param [pramNameN] [description]
    *
    * @return [Description of return value]
    *
    * @exception [full classname of thrown exception] [description]
        ...
    * @exception [full classname of thrown exception] [description]
    *
    * @see [full-]classname[#method-name] [(can have zero or more of these)]
    */
    public static void methodName(pram1Type pramName1, ...,
                                  pramNType pramNameN)  
    {
        stuffHere();
    }
}

Aaltosulut

Aaltosulut ovat omilla riveillään.

 
public static void main(String args[])
{
    System.println(args[1]);
}

If-lauseet

If lauseen ja sulkujen väliin jätetään välilyönti. Aaltosulkuja käytetään vaikka if-lauseen sisään rivejä tulisi vain yksi.

 
if (length > maxLength) 
{
	length = maxLength;
}

Metodit, konstruktorit...

Sulut kirjoitetaan kuitenkin yhteen metodien yms. yhteydessä. Jos funktion parametrit eivät mahdu yhdelle riville, jokainen sijoitetaan omalle rivilleen.

public drawRectangle(DrawArea    drawArea,
                     XCoordinate topLeftX, 
                     YCoordinate topLeftY, 
                     XCoordinate bottomRightX,
                     YCoordinate bottomRightY)
{
    drawArea.rectangle(topLeftX, topLeftY, bottomRightX, bottomRightY);
}

Nimeämiskäytäntöjä

Muuttujat i, j ja k ovat varattu iteraattoreile ja x sekä y koordinaattien käsittelyyn. Kuvaavampia nimiä on kuitenkin käytettävä, mikäli

Luokan aksessorit nimetään get/setAttribuutti. Jos kyse on boolean tyyppisestä attribuutista get = is.

Lisäykset suoritetaan add-alkuisilla ja poistot remove-alkuisilla metodeilla. Muutenkin pyritään noudattamaan java-luokkakirjastojen mukaisia nimeämiskäytäntöjä.