Stilguide

Generelt

Koden må kompilere Koden må kjøre Ikke gjenta deg selv Modulær kode Selvdokumenterende kode Gjør det enkelt

Javadoc

Javadoc for alt som er public og protected Ikke kombiner javadoc og @Override Beskriv returverdi Beskriv sideeffekter Beskriv oppførsel ved null-argumenter Beskriv parametre med @param Beskriv exceptions med @throws Javadoc < 72 tegn

Kommentarer

Ikke undervis Java Unngå unødvendige kommentarer Korte kommentarer Korrekte kommentarer Kommentarer < 80 tegn

Formatering

Innrykk på 2 mellomrom Kodelinjer < 80/100 tegn Bruk mellomrom riktig

Navngivning

Selvbeskrivende navn Korte navn Presise navn Navn på klasser er UpperCamelCase Navn på metoder og variabler er lowerCamelCase Navn på konstanter er UPPER_SNAKE_CASE Navn på pakker er lowercase Kvalifisering med this Kvalifisering med klassenavn

Kodestil

Korte metoder Unngå magiske verdier Unngå statiske variabler Begrens skopet til variabler Bruk parenteser Ikke bruk == med flyttall Ikke bruk == med objekter Benytt hjelpevariabler Små klasser kan være uforanderlige Variabler har abstrakte typer

Innkapsling

Bruk strengeste tilgangsmodifikator Instansvariabler er private

Testing

TestFoo ligger i samme pakke som Foo Test public og protected metoder Test for likhet Test hjørnetilfeller

  /**
   * Multiple lines of Javadoc text are written here,
   * wrapped before the 72 character mark.
   */
  public void methodName() {
    // ...
  }

Korte javadoc-kommentarer kan skrives på én linje

  /** An especially short bit of Javadoc. */
  public void methodName() {
    // ...
  }

// This is an array of ints holding the measured
// temperatures in the order they were registered.
int[] temps;

men skriv heller korte kommentarer som dette:

int[] temps; // in order of registration

Hensikten med denne grensen: lettere å jobbe med split screen, lettere å lese, lettere å presentere koden med stor skrift (spesielt viktig for dine synshemmede kolleger), og lettere å skrive ut.

Vi ser her på bruk av mellomrom som teknisk sett er frivillig, men hvor vi har retningslinjer som gjør koden vår penere å lese.

• Aldri benytt to mellomrom etter hverandre.
• I eksemplene under viser vi mellomrom som symbolet ·.

if·(test)·statement;

if·(test)
  statement;

if·(test)·{
  // ...
}

this.doFoo(42,·"bar");

public void doFoo(int x,·String s)·{
  // ...
}

int x·=·((-a·%·b)·*·Math.abs(2·–·c));

for (int i = 0;·i < 10;·i++) {
  // ...
}

Navn på klasser, metoder og variabler skal være selvbeskrivende. Ideelt sett bør navnet beskrive sin egen rolle såpass godt at det ikke er nødvendig å lese javdoc for å forstå hva metoden gjør eller hva variabelen inneholder.

Jo mer eksponert navnet er, jo viktigere er det at navnet er selvbeskrivende. Derfor er det for eksempel enda viktigere med selvbeskrivende navn for feltvariabler enn for lokale variabler.

Navn på klasser, metoder og variabler skal være presise. For eksempel er getValue et dårlig navn på en metode som returnerer og inkrementerer en verdi: getAndIncrementValue er bedre.

Hvis dennne regelen fører til at navnet på metoden din blir uhåndterlig langt, kan det være et tegn på at metoden har for mange hensikter, og burde vært delt opp i hjelpemetoder.

for (int r = 0; r < 15; r++) {
  // ..
}

men opprett en konstant med selvbeskrivende navn i stedet :

int rows = 15;
for (int r = 0; r < rows; r++) {
  // ..
}

Dersom denne samme verdien (15) brukes annet sted i koden også, skal kanskje de to verdien alltid være synkronisert. Da må de hentes fra samme sted; definer for eksempel verdien som en feltvariabel. Enten som en konstant klassevariabel, eller (ofte enda bedre) du kan bruke en instansvariabel slik at koden blir dynamisk og virker like bra for andre verdier enn 15 også.

Verdier vi ikke regner som magiske er -1, 0, 1, 2, "", og null.

Bruk paranteser når du skriver kombinerte uttrykk. Ikke anta at den som leser koden din har memorisert java sin presedenstabell.

Riktig:

isOk = (x == y) || (x == z)

Feil:

isOk = x == y || x == z

Når du skal velge variabeltype, velg en type som er så høyt oppe i typehierarkiet som mulig, men så lavt som nødvendig. Det er for eksempel bedre om en variabel har typen List<Foo> enn ArrayList<Foo> (såfremt du ikke er avhengig av en metode som finnes i ArrayList men ikke List).