english-banner English version of this page
 
deutsche Flagge
Portait-Photo
über mich

Startseite
Links/BookmarksLinks
Programmieren
   - CodeOptimierung
   - CodeConventionen
   - GFA-Basic

Atari
Hardware-
Basteleien

Witze
Zitate
Sprüche
Braille
Kunst
Buch-Tip
E-Mail an Folke_R@gmx.de
historisches
Impressum

Code-Konventionen / Codierungs-Stil


Übersicht


Vorwort [^]

Wie vermutlich jeder Programmierer, habe ich mir im Laufe der Zeit meine Vorlieben für eine gewisse die Quellcode-Formatierung, Namensbildung etc. angeeignet.

Für ein universitäres Projekt habe ich zu diesem Thema recherchiert und meine Vorlieben mit den Meinungen anderer verglichen und nach Gründen für die einzelnen Konventionen gesucht.
Oft werden von den Verfassern derartiger Regeln leider keinerlei Begründungen geliefert.

Im folgenden finden Sie meine aus dieser Recherche entstandenen Code-Konventionen. Wo möglich, habe ich Argumente für meine Entscheidungen angegeben, um auch Sie von selbigen zu überzeugen.

Auch wenn Die Formulierung der meisten Regeln sich auf Java-Quellcode bezieht, ist fast alles auf die meisten anderen Programmiersprachen übertragbar.



Oberste Regel: [^]

Wenn es der Lesbarkeit / dem Verständnis dient, dürfen alle Regeln ignoriert werden.

Die Anwendung dieser Regel sollte aber stets die Ausnahme sein!



Wozu? [^]

  • Verbesserung der Lesbarkeit
  • Quellcode soll auch ohne die Neuformatierungs-Funktion vieler IDEs gut lesbar/einheitlich sein
  • Wenn Versionierungstools, wie 'CVS' oder 'Subversion' verwendet werden, führt ein Wechsel der Formatierung durch verschiedene Autoren zu großen 'diff-files' und sollte daher vermieden werden.
  • 80% der Kosten während des Lebenszyklusses von Software fallen bei der Wartung an. (SUN)
  • Fast nie wird eine Software bis zum Schluß vom ursprünglichen Autoren gewartet. (SUN)
  • Wenn der Quellcode Teil eines Produktes ist, muß man darauf achten, daß sie 'sauber' ist. (Der Quellcode ist eine Visitenkarte des Unternehmens) (SUN)


Aufbau einer '.java'-Datei [^]

Jegliche Regelung, wie eine Quellcode-Datei aufgebaut sein soll, hilft es sich in fremden Quellcode schneller zurechtzufinden.

Die 'public'-Klasse / das 'public'-Interface soll immer die oberste Klasse/Interface in der Datei sein.

Schematische Aufbau
DateiKommentar
// FILE: Dateiname.java

Wenn man die Datei Ausdruckt ist dies (zusammen mit der 'package'-Angabe eine eindeutige Identifikation.
'class'-/'interface'-Zeile erst weiter unten kommt, Ist diese Angabe am Dateianfang hilfreich.

Problem/Nachteil: Diese Zeile kann von IDEs nicht automatisch an Namensänderungen angepasst werden.

/** javadoc-Kommentar
 */
Eventuell kann man dies auch ohne Aufbau dieses Kommentar-Blocks festlegen. Hier meine Muster-Klasse (Datei ist nicht zum Anzeigen im Browser geeignet sondern sollte in einem Texteditor betrachtet werden (oder laden Sie die Datei in ihre java-IDE)).
class Klasse
static Variablen
instanz Variablen
Konstruktoren
Methoden get- und set-Methoden werden gerne am Anfang der Klasse hinter den Konstruktoren gebündelt.

Ich selber sehe das Zusammenziehen aller Variablen-Deklarationen am Anfang der Klasse nicht so eng. Gerade 'static final'-Konstanten, die nur in einer Methode zum Einsatz kommen deklariere ich gerne direkt vor selbiger anstatt am Anfang der Klasse.

Manche Programmierer legen die Reihenfolge bezüglich ihrer Sichtbarkeit fest. Ich halte aber nichts davon, da ich Methoden, die Inhaltlich zusammen gehören lieber auch im Quellcode beieinander habe, egal wie ihre Sichtbarkeit ist.



Position von Klammern [^]

Ich vertrete die Meinung, das die Regel:
"Klammerpaare sollten immer in der selben Zeile oder der selben Spalte sein" die Lesbarkeit enorm erleichtert.

Daraus ergibt sich das folgende nicht so weit verbreitete Aussehen:

  public int getX()
  {

  }
  while(0<=i)
  {

  }
  do
  {

  }while(1==i%3);
  switch(key)
  {
    1:

  }
  if(gerade)
  {

  }
  else
  {

  }
  public class Test
  {

  }


Einrückungen [^]

Ich rücke immer 2 Leerzeichen ein.

Warum Leerzeichen?

Grund:
Im Gegensatz zu Tabs (Tabulatorzeichen) verändert sich bei der Einrückung mit Leerzeichen nichts in der Darstellung je nach Editor.
Die, oft ungewollte, Vermischung des Einsatzes von Tabs und Leerzeichen führt zu kaputten Formatierungen in Editoren mit anderen Tab-Einstellungen.

Warum 2 Leerzeichen?

Grund:
Verwendet man deutlich mehr, so ist bei mehrfacher Einrückung nicht mehr viel vom Code im Editor zu sehen, ohne extra zu scrollen.
Ein anderer Grund dürfte meine Vorschädigung durch die erste IDE sein, die ich benutzte (GFA-Basic-Editor). Sie nutzte genau 2 Leerzeichen für die automatische Einrückung verwendete.



Zeilenlänge [^]

80 Zeichen pro Zeile sollte nur in Ausnahmen überschritten werden.

Grund:
Längere Zeilen werden auf vielen Terminals und Tools nicht geeignet behandelt. (SUN)

Zeilen sollte ohne Scrollen im Editor, wenn möglich, ganz sichtbar sein. Weil früher auf Terminals nur 80-Zeichen pro Zeile dargestellt wurden, heute sind es bei nicht zu kleiner Font-Wahl meist auch nicht viel mehr, ist diese Schranke noch immer aktuell.



Zeilenumbrüche [^]

Nach einem Zeilenumbruch sollte immer die Einrückung beibehalten werden. Wenn es die Lesbarkeit verbessert, kann aber auch mehr eingerückt werden!



Kommentare [^]

Wo nötig sollte der Code kommentiert werden. Wenn man das Gefühl hat, daß man zum Verständnis viele Kommentare braucht, ist das ein Hinweis auf schlechten Code! (SUN)

Zwar ist kein Code so klar, daß auf Kommentare ganz verzichtet werden kann, doch sollte der Code so leicht verständlich, wie möglich sein.

Befor man einen Kommentar schreibt sollte man nachdenken, ob man nicht stattdessen den Code klarer verständlich schreiben kann.

Alle Dinge, die nicht direkt aus dem Code hervorgehen, sollten kommentiert werden. Zudem die übergeordnete Idee, die zu dieser Implementierung geführt hat.

In den /** ... */ Javadoc-Kommentaren sollten keine Dinge der Implementierung beschrieben werden, da

  • Die Implementierung nach außen nicht sichtbar sein sollte.
  • Die Implementierung sich ändern könnte und die doppelte Kommentierung im Code und in dem Javadoc-Kommentar erfahrungsgemäß nicht konsistent gehalten werden. (SUN)
Folgerung: Kommentare zur Implementierung nur an geeigneter Stelle im Code machen.

Um die Struktur des Codes leicht ersichtlich zu lassen, sollte man Kommentare genauso weit, wie den Code einrücken

Kommentare am Zeilenende sollten nur gemacht werden, wenn sie kurz sind (sollten die 80 Zeichen-Regel nicht verletzen) und sollten deutlich von Code getrennt sein, um die Lesbarkeit zu erleichtern



Deklarationen [^]

Pro Zeile sollten in der Regel nur eine Deklaration stehen.

Ausnahme stellen Variablen dar, die Inhaltlich zusammengehören
z.B. int x, y;

Grund:
Die Lesbarkeit wird erhöht, da Deklarationen leichter erkennbar und Änderungen einfach durch einfügen/löschen von Zeilen gemacht werden können.

Nie sollten Arrays und 'Nicht-Arrays' in einer Zeile deklariert werden.

Grund:
Gemischte Deklarationen von Arrays und 'Nicht-Arrays' sind sehr unübersichtlich / verwirrend.



Positionierung der Deklaration in Methoden [^]

Variablen sollten erst unmittelbar vor der Nutzung deklariert werden nicht etwa schon am Anfang der Methode.

Grund:

  • Es wird sofort klar, wofür die Variablen gebraucht werden.
  • Speicher wird erst wenn nötig alloziert (wenn in einem bedingten Abschnitt also eventuell gar nicht)
  • es können während der Implementierungen ohne viel hin- und her-springen im Code Änderungen vorgenommen werden.



Initialisierung [^]

Wenn möglich gleich bei der Deklaration

Grund:

  • Man erkennt sofort, was der Variablen zugewiesen wird und muß nicht erst nach allen verstreuten Zuweisungen suchen.
  • Eventuelle Zuweisungen von Defaultwerten durch die VM wird eingespart.



Leerzeichen [^]

keine Leerzeichen vor runden Klammern bei Methoden, und Kontrollstrukturen (if( ), while( ), switch( )).

OKNICHT

  public int getX()
  {

  }

  public int getX ()
  {

  }

  while(10!=i)
  {

  }

  while (10!=i)
  {

  }

  if(10!=i)
  {

  }

  if (10!=i)
  {

  }

  switch(key)
  {

  }

  switch (key)
  {

  }

  do
  {

  }while(7==i);

  do
  {

  }while (7==i);

Grund:
Die Klammer gehören fest zu dem vorderen Teil, und sollte zur besseren Lesbarkeit nicht abgetrennt werden.



'do .. while'-Schleifen [^]

Vermeiden Sie die Nutzung dieses Schleifentyps!

Grund:

  • Bedingungen am Schleifenende machen den Code schwerer lesbar.
  • Versehentliches löschen der 'do'-Zeile hinterläßt syntaktisch korrekten Code (meist mit einer Endlosschleife) und wird daher vom Compiler nicht beanstandet.
    korrekter Fall Fehlerfall
    Endlosschleife
    
      int i=0;
      do
      {
        i++;
      }while(10>i);
    
      int i=0;
      {
        i++;
      }while(10>i);

    Der rechte Fall ist ein Block gefolgt von einer leeren while-Schleife.

    Dieser Fehler hat mich stundenlange Fehlersuche gekostet.



Ausdrücke [^]

Nur einen Ausdruck pro Zeile!
OKNICHT
  i++;
  value+=4;
  i++; value+=4;

Grund:
Lesbarkeit.



zusammengefaßte Ausdrücke (in {}) [^]

for, while, do..while, if, else.
Auch einzelne Ausdrücke in einen {}-Block packen (Aus rein optischen Gründen verstoße ich selbst regelmäßig gegen diese Regel)

Grund:

  • späteres hinzufügen eines weiteren Ausdrucks wird erleichtert
  • vermeiden des klassischen verschachtelten if-else-Fehler:
    falsch eingerückter Code eigentlich gemeint mit allen {}
    
      if(2==a)
        if(4==b)
          x=7;
      else
        x=5;
     
    
      if(2==a)
      { if(4==b)
          x=7;
      }
      else
        x=5;
     
    
      if(2==a)
      {
        if(4==b)
        {
          x=7;
        }
      }
      else
      {
        x=5;
      }
In dem Fall mit allen {} wäre die fehlerhafte Formatierung sofort aufgefallen. Und damit auch das vermeintlich ungewollte Verhalten.



Die switch-Anweisung [^]

0. Vermeiden sie 'fall-through'

1. kommentieren sie absichtliches 'fall-through'


  switch(c)
  {
    3:
      x=2;
      //FALLS THROUGH
    4:
      x++;
      break;
    5:
      x=6;
      break;
    default:
      x=0;
  }

Grund:
Oft wird versehentlich die 'break'-Anweisung vergessen. Um deutlich zu machen, daß es sich um Absicht handelt, sollte man das dokumentieren. (z.B. der jikes-Compiler warnt auch wenn 'fall-through's im Code vorkommen!)



Leerzeilen [^]

Leerzeilen verbessern die Lesbarkeit des Code, wenn sie logische Abschnitte trennen.

Ich empfehle zumindest eine Leerzeile zwischen Methoden



Leerzeichen [^]

Immer nach ',' und nie bei den einstelligen Operatoren '-', '--', '++'

Grund:
Ich finde das verbessert die Lesbarkeit.



Namenskonventionen [^]

Ich nenne die fast immer verwendeten Regeln für die Schreibweisen.

  • 'class'-/'interface'-Namen: beginnen mit einem Großbuchstaben, der Rest klein (Abkürzungen sollen nicht verwendet werden, es sei denn sie sind sehr gebräuchlich)
  • Methoden-Namen: erster Buchstabe klein
  • Variablen-Namen: erster Buchstabe klein. Sprechende Namen außer z.B. für Schleifenzähler
  • Konstanten-Namen: komplett in Großbuchstaben mit '_' zum Trennen von Worten. z.B. TAGE_PRO_JAHR

Grund:
Diese Regeln sind unter den meisten Programmierern verbreitet und sorgen daher bei Einhaltung zu leichterer Lesbarkeit.



'public'-Variablen [^]

Variablen sollten nur public sein, wenn es sich um reine Datenstrukturen, ohne Funktionalität, handelt. Viele fordern sogar ganz auf 'public'-Variablen zu verzichten und immer über get- / set-Methoden zuzugreifen.

Grund:
'public'-Variablen geben einen direkten Blick auf die Implementierung frei, deshalb widerspricht das schon ideell gegen die objektorientierte Sicht.

Wenn es 'public'-Variablen gibt, kann dieser Teil der Implementierung später nie mehr geändert werden!



Zugriff auf statische Methoden [^]

Greifen Sie nie über Instanzen einer Klasse auf deren statische Methoden zu. Greifen Sie immer über den Klassennamen zu.

Grund:
Bis ich das einmal gesehen harte, wußte ich gar nicht, daß man so etwas unschönes machen kann.

Wenn man über den Klassennamen die statischen Methoden zugreift ist es unmöglich diese ausversehen für Instanzmethoden zu halten.



Konstanten [^]

Vermeiden Sie konkrete Werte im Code zu verwenden. Benennen Sie lieber sprechende Konstanten, die Sie dann im Code verwenden. Vor allem vor 'Magic-Numbers' sei gewarnt. Sie erschweren die Lesbarkeit und machen spätere Änderungen unnötig schwer.
(z.B. -1 steht für ungültiger Parameter, -2 für alles OK ...)

Grund:
Wie oben schon beschrieben ist die Lesbarkeit und Wartbarkeit deutlich verbessert, wenn man sprechende Konstantennamen einsetzt.



der ?:-Operator [^]

Schreiben Sie die Bedingung in Klammern!

Grund:
Das erhöht die Lesbarkeit erheblich



Klammern [^]

Schreiben Sie lieber mehr als weniger Klammern!

Grund:
Nicht jeder kennt die Vorrangregeln aller Operatoren auswendig. Da ist der Leser dankbar über jede Klammer, die das Lesen erleichtert.



spezielle Kommentare [^]

Vereinbaren Sie in Projekten spezielle Kommentare wie:
//FIXME
//TO BE IMPLEMENTED
//DEBUG
//INFO
//???
//!!!

Grund:
Einheitlich markierte Stellen kann jeder schnell finden.



'final'-Variablen [^]

Variablen sollten wann immer möglich als final deklariert werden. Vor allem Methodenparameter.

Grund:

  • Lesbarkeit erhöht sich. Jede zusätzliche Information hilft dem Leser!
  • versehentliches verändern eigentlich nicht zum Ändern gedachter Variablen wird sofort vom Compiler unterbunden.
  • Eventuell hilft das dem Compiler / der VM Optimierungen vorzunehmen.


Hinweis: [^]

Methoden/Funktionen, die sehr lang sind (mehr als 100 Zeilen (Kommentare nicht mitgerechnet)) sind meist ein Hinweis darauf, daß Ihre Funktionalität, aus Übersichtlichkeitsgründen, lieber auf mehrerer aufgeteilt werden sollte.

Das selbe gilt für Klassen (2000 Zeilen hielt SUN hier für eine magische Grenze).



Verwendete Abkürzungen/Namen: [^]
IDE:Entwicklungsumgebung, wie z.B. Eclipse, JBuilder
VM :'Virtual Maschine' : z.B. die java Virtuelle Maschine
jikes:Ein java-Compiler (empfohlen, da viel schneller als javac und oft hilfreichere Fehlermeldungen)

Verwendete Quellen: [^]
sonstige URLs: [^]
  • jikes ein java-Compiler (sehr viel schneller als javac und oft auch hilfreichere Fehlermeldungen und Warnungen)
    (http://jikes.sourceforge.net)
  • eclipse Eine freie Entwicklungsumgebung, allerdings ein ziemlicher RAM-Fresser)
    (http://www.eclipse.org)

Ich bin immer an Kommentaren zu meinen Code-Konventionen oder Vorschlägen zu weiteren (bitte mit Begründung) interessiert. Schreiben Sie mir doch einfach eine E-Mail an Folke_R@gmx.de.

zurück zur Programmier-Seite des Folkes
zurück zur Startseite des Folkes
Lage dieser Seite:"http://www.rinneberg.de/programming/codeconventions.htm"
"http://www.Folke-Rinneberg.de/programming/codeconventions.htm"

Stand: 15.12.2007 (Inhaltlich: 23.04.2007)         Brief an Folke:(Folke_R@gmx.de)

JBuilder, jikes, Eclipse, GFA-Basic, SUN Microsystems, ... sind geschützte Bezeichnungen der entsprechenden Firmen.
Link zu dieser Seite:

Sie haben eine Internetseite und finden meine Seite gut? Dann wäre es nett, wenn Sie einen Link zu meiner hinzufügen.
(währe schön wenn der Linktext 'Folke' 'Rinneberg' und das Thema der Seite beinhalten würden. z.B. 'Code-Konventionen von Folke Rinneberg')

Haben Sie eine Seite zum gleichen Thema? Schicken Sie mir eine E-Mail mit der URL (Betreff: 'HOMEPAGE: Link (hier Ihre URL einfügen)'). Vielleicht setze ich einen Link.

Benachrichtigung über Änderungen dieser Seite:

Wollen sie informiert werden, wenn sich der Inhalt dieser Seite ändert? Schicken Sie mir eine E-Mail mit dem Betreff: 'HOMEPAGE: informiere mich (www.rinneberg.de/programming/codeconventions.htm)'.
(Ihre E-Mail-Adresse wird nicht weitergegeben und ich versende auch keinerlei Werbung)


Ende des deutschsprachigen Abschnitts
german-line

 
english-line
Start of the English translated part
english banner
Portait-Photo
about myself

Home
Links/Bookmarkslinks
programming
   - CodeOptimisation
   - CodeConventions
   - GFA-basic

Atari
hardware-
modifications

jokes
quotations
patter
braille
art
book-tip
E-Mail an Folke_R@gmx.de
history
imprint

Code-Conventions / Coding-Style


Content


preface [^]

I think, like every other programmer, I made my mind about how source-code should look like. This page lists my preferred rules to write well readable source code.

For one software-project in the university I searched for code conventions of other programmers and what reasons exists for them, because we had to decide which conventions we should use in our project.
In most cases the authors of such conventions did not mention their reasons for their rules.

On the rest of this page you will find my code conventions and, wherever possible, reasons for them.

The rules mainly refer to java-code but can be quite easily transferred to nearly all other programming languages.



the top rule: [^]

If it increases readability / easy understanding you may ignore all rules!

You should use this rule only as an exception.



why do we need code-conventions? [^]

  • make reading more easy
  • source code should be readable and always formatted the same way, without using a auto-formatting feature supported by most IDEs
  • If you use a versioning tool like 'CVS' or 'Subversion' , a change in the formatting by different authors leads to big 'diff-files' and should therefore be avoided.
  • 80% of the costs while the usage of software is maintenance. (SUN)
  • In nearly no case is software until its end of usage maintained by the same author. (SUN)
  • If the source code is part of your product, it should be 'clean'. (The source code is a visiting card of the company) (SUN)


structure of a '.java'-File [^]

Whatever convention you use how your source code files are structured will help new authors to find things faster in your code.

The 'public'-class / the 'public'-interface should always be the topmost class / interface in a file.

schematic structure
filecomment
// FILE: Filename.java

If you print a file on a paper is this line together with the 'package'-information a unique identification.
Because of the fact that the 'class'-/'interface'-declaration follows maybe a lot of lines later, this comment line is useful to recognise the file with one look.

problem/disadvantage: IDEs may not be able to generate this comment line automatically. And refactor (change of the classname) must be propagated to this comment line by the programmer himself.

/** javadoc-comment
 */
You may also make conventions how this comment should be structured.
This is mine pattern-class (This file is not meant to be displayed with a web browser. You should store the file and have a look at it with a text editor (or load the file in any java IDE).
class Name
static variables
instance variables
constructors
methods All get- and set-methods are often put to the top of the class directly behind the constructors.

I myself think it is most times useful, but not always to group all variable declarations at the top of the class declaration. Especially 'static final'-constants, which are used in only one method may be declared directly before this method instead of the top of the class.

Some programmers use conventions in which order the methods should be declared (p.e. in order of visibility). I think this is nearly never a help for easier reading the code. The order should depend of the functionality. If a private method is only used my one public one I think it is useful to group both methods near to each other.



position of brackets [^]

My opinion is that the rule:
"Pairs of brackets should always be in the same line or column".
increases the readability a lot.

The result of this rule is the following not widely used appearance:

  public int getX()
  {

  }
  while(0<=i)
  {

  }
  do
  {

  }while(1==i%3);
  switch(key)
  {
    1:

  }
  if(even)
  {

  }
  else
  {

  }
  public class Test
  {

  }


indent [^]

I use two spaces to indent blocks.

why space characters?

Reason:
In contrast to tab-characters, space characters look equal in every editor or IDE.
Programmer who use tab-character often accidentally mix the usage or space- and tab-characters. This leads to destroyed indent in editors which use a different indent for a tab than the editor the original author used.

why two space characters?

Reason:
If you use a lot more than two (p.e. eight), multiple indents make your code 'disappear' at the right side of your editor and you must scroll to see the code.
Another reason may be that the first IDE I ever used, used two spaces for the auto-indent of blocks (it was the GFA-Basic-Editor on my ATARI-ST).



line length [^]

You should not write more than 80 characters in one line.

Reason:
Lines which are longer cannot be handled properly by some terminals and tools. (SUN)

If possible the hole line should be displayed in your editor without the need of horizontal scrolling. Some time ago, terminals could only display 80 characters per line, and nowadays it is mostly not a lot more (if you did not use a very tiny font). Therefore the 80 characters rule is still valid.



line breaks [^]

After each line break the indent should still be the same. If it increases readability, you may increase the indent (p.e. if you cut a line in more lines because it would be too long it is sometimes better to make extra indent).



comments [^]

Wherever needed, you should comment your code. If you think a comment is needed to understand your code, it may be a hint that your code is bad! (SUN)

It is true that no program code can live totally without comments, but code should be as easy readable even without extra comments as possible.

Before you add a comment to your code, think if an other implementation would be clearer and would therefore not need this comment. Code which needs less comments is always to be preferred.

Everything which could not be understand directly by reading the code must be documented in comments. Especially the main idea of an implemented algorithm or the implemented idea must be documented for easy understanding by readers which are not the author of the code.

In /** ... */ javadoc-comments you should never document implementation specific informations, because

  • the implementation should encapsulated in the class and not visible from outside of the class .
  • the implementation may change while the lifetime of the class and the practice shows the documentation at more than one position (p.e. in the code and in the javadoc-comments) leads to the fact that at least one of them get out of date because not updated properly. (SUN)
Conclusion: Comments about the implementation should only be at a proper position in your code.

If you indent your comments as much as the code around them, the structure of the code can easier be recognised than if you need other or no indent for your comments.

Comments attached to the end of a line should be only used if they are very short and did not violate the 80 characters per line rule to have best possible readability.



declarations [^]

In each line should be only one declaration.

Exceptions are variables with a common content like p.e.
int x, y;

Reason:
The readability is increased if different declaration are in different lines, because a reader can find a special one faster.
An other reason is that insertion and deletion of lines can be used when a variable is no longer used or a new one is needed.

Never declare arrays and 'non-arrays' in the same line.

Reason:
Mixing declarations of arrays and 'non-arrays' is very confusing for the reader.



position of declarations in methods [^]

Variables should be declared directly before the use not all at the beginning of a method.

Reason:

  • It is immediately clear what the variable is used for.
  • Memory is not allocated before needed (If the variable is only used under several conditions the memory may never be allocated.).
  • If you want to change something in your code you have not to jump between the line with the declaration and the lines where the variable is used. (p.e. refactoring of the variable name, type, initialisation)



initialising [^]

If possible, initialise the variables directly when you declare them.

Reason:

  • The reader recognises immediately what value the variable is initialised with. You do not need to search in the code.
  • In some cases you save the initialisation of a variable by your VM.



spaces [^]

no spaces before round brackets of methods, and constructors (if( ), while( ), switch( )).

GOODBAD

  public int getX()
  {

  }

  public int getX ()
  {

  }

  while(10!=i)
  {

  }

  while (10!=i)
  {

  }

  if(10!=i)
  {

  }

  if (10!=i)
  {

  }

  switch(key)
  {

  }

  switch (key)
  {

  }

  do
  {

  }while(7==i);

  do
  {

  }while (7==i);

Reason:
The brackets are a direct part of the previous part and should therefore not be separated from it by spaces for good readability.



'do .. while'-loops [^]

Avoids loops of this type!

Reason:

  • Condition at the tail of a loop make your code harder to understand/read.
  • If you accidentally delete the 'do'-line, the rest of your code is still syntactically correct (the resulting code is most times an infinite loop) and can be compiled without any errors or warnings.
    The correct code the error
    infinite loop
    
      int i=0;
      do
      {
        i++;
      }while(10>i);
    
      int i=0;
      {
        i++;
      }while(10>i);

    The right case the code represents a code block followed by an empty while-loop.

    I once needed hours of debugging to find an error of this kind.



expressions [^]

Only one expression per line!
OKNOT
  i++;
  value+=4;
  i++; value+=4;

Reason:
Readability.



(in {}) blocked expressions [^]

for, while, do..while, if, else.
Even if there is only one expression, put it in a {}-block (I myself ignore this rule quite often because the look is often better, if you did not use the brackets)

Reason:

  • if you want to add expressions later, it is easier, if there are already a {}-block
  • if you did not use the {}-block, you may get a victim of the classical if-else-error:
    code with wrong indent this was meant by the programmer code with all {}-blocks
    
      if(2==a)
        if(4==b)
          x=7;
      else
        x=5;
     
    
      if(2==a)
      { if(4==b)
          x=7;
      }
      else
        x=5;
     
    
      if(2==a)
      {
        if(4==b)
        {
          x=7;
        }
      }
      else
      {
        x=5;
      }
In the case with all {}-blocks the programmer would have seen immediately the wrong indent. And therefore would have also avoided the unwanted behaviour of the code.



the switch-operator [^]

0. Do avoid 'fall-through'

1. comment if you made a 'fall-through' with intention


  switch(c)
  {
    3:
      x=2;
      //FALLS THROUGH
    4:
      x++;
      break;
    5:
      x=6;
      break;
    default:
      x=0;
  }

Reason:
Quite often the 'break' is missing my mistake. To make clear that the missing 'break' intended by the programmer he should comment this. (p.e. the jikes-compiler warns if a code consists 'fall-through's!)



free lines [^]

Free lines increase the readability of code, if they are used to make the logical structure clearer.

I recommend to use free lines at least between methods.



spaces [^]

Every time after ',' and never before unary operators '-', '--', '++'

Reason:
My opinion is that this increases the readability.



naming conventions [^]

Here I only mention the conventions used by nearly all java-programmers.

  • 'class'-/'interface'-names: Starting with a capital letter, the rest of the letters lower-case. (abbreviations should be avoided, if they are not extremely commonly used)
  • method-names: first letter lower case
  • variable-names: first letter lower case. Use speaking names not one-letter names exceptions are variables for loop-counting.
  • names of constants: all letters upper case separate words with '_'. p.e. DAYS_PER_YEAR

Reason:
This conventions are extremely widely used out there and nearly any programmer knows them and expects them to be used by others, too. Therefore every violation of this conventions lead to worse readability.



'public'-variables [^]

variables should only be public, if the class is only a data structure with no methods. Quite a lot of programmers say you should totally avoid 'public'-variables and always use get- / set-methods to access variables.

Reason:
'public'-variables let you see a part of the implementation, which violates the object orientated idea of hiding the implementation.

If you use 'public'-variables, this part of the implementation can never be changed!



access to static methods [^]

Do never access static methods by using instances of the class. Use always the classname to access static methods.

Reason:
Until I once saw this ugly way to access static methods, I did not even know that it is possible this way.

If you use the classname to access static methods, the reader can not accidentally think a static method is instance method.



constants [^]

Avoid to use concrete values in your code. Better make constants with good names and use them within the code. Especially 'magic-numbers' should be avoided. They decrease readability and make changes in the future more difficult.
(p.e. -1 stands for 'prong parameter-value', -2 stands for 'everything is OK' ...)

Reason:
Readability an later changes are much more easy, if you use constants with good names.



the ?:-operator [^]

Always put the condition in brackets!

Reason:
This increases readability a lot.



brackets [^]

More brackets are better than few!

Reason:
Not everyone knows the binding power of all operators. Therefore the readability increases if you put brackets at not so clear positions.



special comments [^]

Make an agreement about special comments to be used in your project like p.e.:
//FIXME
//TO BE IMPLEMENTED
//DEBUG
//INFO
//???
//!!!

Reason:
If all authors of a project use the same comments, everyone can easily find this positions.



'final'-variables [^]

Variables should be declared as final whenever possible. Especially the parameters of methods.

Reason:

  • Readability increases. Everyone who reads the code immediately knows that the value of this variable will never change!
  • you can not accidentally change the value of variables which were planned to be constant because the compiler will throw an error if you declared the variable as final.
  • Maybe this helps your compiler / VM to optimise your code.


hint: [^]

methods/functions, which need a lot lines of code (more than 100 (comment lines not counted)) are most times a hint that the functionality may be split in more methods to make the code easier to understand.

The same is true for classes (2000 lines are meant to be a magic boarder not to cross (SUN)).



names and abbreviations: [^]
IDE:Development environment, like p.e. Eclipse, JBuilder
VM :'virtual machine' : p.e. the java virtual machine
jikes:a java-Compiler (better use this one than the javac, because it is a lot faster than javac and often mention more helpful error messages and warnings)

external sources used: [^]
other URLs: [^]
  • jikes a java-compiler (a lot faster than javac and often mention more helpful error messages and warnings)
    (http://jikes.sourceforge.net)
  • eclipse a open source development environment, but needs quite a lot of RAM)
    (http://www.eclipse.org)

I am always interested in comments about my code-conventions and proposals for more conventions (please with reasons). Write me an e-mail to Folke_R@gmx.de.

back to Folke's programming page
back to Folke's homepage
Location of this page: "http://www.rinneberg.de/programming/codeconventions.htm"
"http://www.Folke-Rinneberg.de/programming/codeconventions.htm"

last updated: 15.12.2007 (content: 21.08.2007)         e-mail to Folke:(Folke_R@gmx.de)
JBuilder, jikes, Eclipse, GFA-Basic, SUN Microsystems, ... are protected (trademarks, etc.) names by the corresponding companies.
Link this web site:

You have your own web site and like mine? It would be nice to add a link to mine.
(would be nice, if the link-text would contain the words 'Folke' 'Rinneberg' and something about the content of the page. e.g. 'Code-Conventions of Folke Rinneberg')

If you have similar content on your web page, write me an e-mail with the URL (subject: 'HOMEPAGE: link (insert your URL here)'). I possibly add a link to it on this site.

Be informed of content changes:

You want to be informed, if the content of this page has changed? Then write me an e-mail with the subject: 'HOMEPAGE: remind me (www.rinneberg.de/programming/codeconventions.htm)'
(Your e-mail address will not be given to anyone else than me and I will also not send any ads)

Help to improve this web page:

Because I am no native English speaker, it is likely that there can be made a lot of improvements to my translation. I am very interested in every proposal how to improve the English part of this web page.