Java vett och etikett


Här kommer ett antal regler för hur man organiserar och formaterar sin Javakod. Dessa regler följer man om man inte har har mycket goda skäl att bryta mot dem.

Namn på identifierare
Använd beskrivande namn. Om namnen blir långa så skiljer vi delarna åt med versaler. En funktion som omvandlar en sträng till ett heltal döper vi alltså till stringToInt().
  • Klasser och gränssnitt börjar alltid med stor bokstav: String, Enumeration, etc.
  • Övriga indentifierare börjar aldrig med stor bokstav.
  • Men, det är vanligt att man använder endast versaler när man namnger konstanter: MAX_SIZE_OF_DATABASE.
  • Variabelnamn är oftast substantiv medan metodnamn är verb.
Hjälpvariabler har däremot korta och standardiserade namn.
  • i, j, k betecknar heltal.
  • x, y, z kan vara koordinater eller flyttal.
  • En anonym sträng heter s eller str och ett anonymt tecken c eller ch.
  • En anonym fil heter f.
  • En temporär variabel heter tmp eller temp.
  • En slaskvariabel döper vi till dummy, foo eller bar.
  • Argumentet till main-funktionen heter args.

Indentering
  • Indentera koden i ett block fyra blanktecken.
  • Om kroppen i en loop, if-sats eller else-del består av endast en sats, så står denna på en egen rad med fyra blankteckens indentering.
  • Placera {-tecknet sist på raden och motsvarande } så att det kommer rakt under början på satsen. Exempel:
       while (i < FULL) {
           i++;
           System.out.println("Index: " + i);
       }
    
  • Formatera else-satser på följande sätt:
       if (expr) {           if (expr)
           statement1;           statement1;
           statement2;       else
       } else                    statement2;
           statement3;
    
  • Men om vi har en if-sats inuti else-delen så gör vi så här:
       if (expr1) {
           statement1;
           statement2;
       } else if (expr2)
           statement3;
       else if (expr3) {
           statement4;
           statement5;
       } else {
           statement6;
           statement7;
       }
    

Dokumentation
Du kan anta att läsaren känner till språket Java. Du skriver alltså inte:
   // Add 1 to i
   i++;
Men kom ihåg att läsaren inte vet vad programmet och koden är tänkt att göra; berätta det för henne.
     Varje fil inleds med ett kommentarblock som innehåller åtminstone följande information.
  • Programmerarens namn, signatur, E-post, etc.
  • Datum då koden skrevs.
  • En lista med daterade ändringar.
Varje klass, gränssnitt och metod börjar med ett kort kommentarblock som beskriver dess roll.
     Du kan också använda javadoc, ett automatiskt dokumentationssystem som extraherar information ur klass-, gränssnitts- och metoddeklarationer, samt kommentarer av typen /** */ och sammanställer detta till en översiktlig dokumentation i HTML-format.

Referenser
Code Conventions for Java är en mera utförlig stilguide.




Stefan Nilsson
2000-01-14