Ü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.

// FILE: Dateiname.java

/** javadoc-Kommentar
 */

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.

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.

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)

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( )).

  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!

OK	NICHT
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; }

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).

• SUN Microsystems: "Java Code Conventions"
  (http://java.sun.com/docs/codeconv/html/CodeConventions.doc.html)
• Java Language Coding Guidelines
  (http://horstmann.com/bigj/style.html)
• http://geosoft.no/development/javastyle.html

• 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)

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.

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)

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.

// FILE: Filename.java

/** javadoc-comment
 */

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.

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.

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)

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( )).

  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!

OK	NOT
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; }

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)).

• SUN Microsystems: "Java Code Conventions"
  (http://java.sun.com/docs/codeconv/html/CodeConventions.doc.html)
• Java Language Coding Guidelines
  (http://horstmann.com/bigj/style.html)
• http://geosoft.no/development/javastyle.html

• 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)

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.

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)

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.