Kodningsregler

1. Namngivning

1. Klassnamn skall börja med VERSAL följt av gemener. Enstaka versaler kan användas för att öka läsbarheten. Exempel: Bank, BankAccount.
2. Attribut, metoder och lokala variabler skrivs med gemena bokstäver. När ett namn består av flera ord ökar läsbarheten om första bokstaven skrivs som versal - dock inte som första bokstav i namnet. Exempel: numberOfCars, hasNextInt.
3. Konstanter (attribut deklarerade som final) samt värden i enum-typer) skrivs genomgående med VERSALER. Använd understrykningstecken för att öka läsbarheten. Exempel: LINES_PER_PAGE.
4. Namn på klasser, metoder och instans- och klassvariabler skall tydligt ange vad de står för vilket sällan enbokstavsnamn gör.
5. Lokala variabler KAN ges enbokstavsnamn så länge betydelsen är klar.
6. Använd inte nationella bokstäver (å, ä, ö, ü, é ...) i namn. Java tillåter visserligen detta men de ställer ofta till problem dels vid överföring av kod mellan olika system och dels vid användning av vektygsprogram som t ex Javadoc.

2. Kommentarer

1. Kommentarer skall skrivas på engelska. Nationella tecken (å, ä, ö, ... ) kan göra programmet okompilerbart även om de bara står i kommentarer!
2. Varje klass skall inledas med en javadoc-kommentar som kort beskrivning av syftet med klassen.
3. Varje metod och dess parametrar skall dokumeteras enligt javadoc-standarden (inte alltid nödvändigt om metodens syfte är uppenbart - t ex toString).
4. Namngivning, layout och struktur är de viktigaste medlen för att göra koden begriplig! Kommentera inte självklarheter! Förutsätt att den som läser koden kan Java och är någorlunda insatt i problemet. Ett välskrivet program behöver sällan kommentarer utöver ovan nämnda javadoc.
5. Se till att kommentarerna inte skymmer koden! Javadoc-kommentarerna ska ligga i block i början av klassen och före varje metod. Övriga kommentarer läggs till höger så att det går att går att obehindrat läsa koden.
6. Skriv inte självklarhet i kommentarerna (typ "i++; //i ökas med 1").

3. Programlayout

1. Indentera raderna systematiskt och enhetligt. Se exemplet
2. Skriv alltid ny sats på ny rad.
3. Skriv inte längre rader än som ryms i fönstret.
4. Bryt satser som som är för långa för en rad efter ett kommatecken eller en operator.
5. Ha alltid exakt en tom rad före varje metod.
6. Ytterst sällan behövs mer än en tom rad - för många tomma rader gör koden svåröverskådlig.
7. Ett nyckelord följt av en parentes skall alltid åtskiljas med ett blanktecken.
   while (true) { ... }
8. Använd alltid klammertecknen ({}) kring grenarna i if-satsen och looparna i while- och for-satserna.
9. Ett kommatecken skall alltid följas av ett blanktecken.
10. Omge alltid operatorer av låg prioritet (tilldelnings-, additions-, subtraktions- och relationsoperatorer) med blanktecken.
11. Följande två varianter av placering av klammerparenteserna är tillåtna:

    if (x < y) { ... ... } else { ... ... }

    if (x < y) { ... ... } else { ... ... }

    Den vänstra ger dock mest läsbar kod och är därför att föredraga.

4. Andra viktiga saker att tänka på

1. Instans- och klassvariabler skall deklareras som private eller protected.
2. Endast begrepp som är naturliga attribut skall deklareras som instansvariabler. Hjälpvariabler i metoder skall deklareras lokalt i metoderna.
3. Återanvänd kod genom att anropa metoder - INTE genom "klipp och klistra".
4. Upprepa inte identisk eller nästan identisk kod - anropa metoder i stället!
5. Metoder som gör beräkningar (i vid bemärkelse) skall sällan eller aldrig göra utskrifter (System.out.println). Det är koden som anropar metoden som avgör vad som skall göras med resultatet. Utskrifter skall normal bara göras från main eller från metoder som är designade just för utskrift.
6. Metoder bör kontrollera att parametrarna har legala värden. Om ett illegalt värde upptäcks ska detta rapporteras med throw, assert eller, i brist på bättre insikter i Java, med en felutskrift och programavbrott (System.exit(0)).
7. Inför inte onödiga variabler.
   Skriv alltså INTE så här
   double area = width*height; return area;
   utan så här
   return width*height;
   Det betyder inte att att man inte får strukturera större uttryck med hjälp av extravariabler.
8. Utskrifter ska gå att förstå utan att läsa källkoden.
9. Det ska gå att förstå vad programmet väntar sig vid inmatning utan att läsa källkoden.
10. Koden ska inte innehålla så kallade "magic numbers" alltså odokumenterade numeriska konstanter. Ge dem namn och värde på ett ställe. Exempel:
    final int NAP_TIME = 10; final double INITIAL_TIME_STEP = 0.1;
    Då vet man vad de betyder när man ser dem i koden och om man vill ändra på dem så görs det på ETT ställe. (De behöver inte nödvändigtvis skrivas med versaler även om det ger en extra tydlighet.)

    Konstanter deklarerade med final KAN göras publika.

11. Skriv alltid this. framför instansvariabler i konstruktorer och set-metoder.

Exempel