Programmierrichtlinien für Java-Programme

Diese Programmierrichtlinien sind ein Vorschlag für gut lesbare Java-Programme. Andere Richtlinien können ebenfalls zu gut lesbaren Programmen führen. Bei schlecht lesbaren Programmen müssen die Tutoren entsprechend Punktabzüge vornehmen. Für andere Programmiersprachen gibt es ähnliche Richtlinien, z.B. PASCAL.

1. Allgemeines

1. Dateiendung: .java
2. Genau eine public-Klasse oder ein Interface pro Datei.
3. Nicht mehr als 80 Zeichen pro Zeile schreiben. Mehr als 1000 Zeilen pro Klasse gelten als unnormal und sind meistens vermeidbar.
4. Pro Zeile darf nicht mehr als eine Anweisung stehen. Mehrere Zuweisungen in einer Zeile sind zu vermeiden.
5. Zu lange Anweisungen dürfen auf mehrere Zeilen verteilt werden. Es ist darauf zu achten, dass solche Anweisungen an einer Stelle umgebrochen werden, so dass sich der Sinn der Anweisung möglichst leicht erschließen lässt.
6. Die Deklaration von Variablen soll nur am Anfang von Blöcken gemacht werden (nach "{"). Ausnahme: Innerhalb von for-Schleifen:

   	for (int i=0; i<y ; i++) {
   		...
   	}
   

7. Leerzeilen sollen Abschnitte bilden, so dass Sinnverwandtes auf den ersten Blick als ein Block erkannt werden kann.
8. Zwischen Methodendeklarationen ist mindestens eine Leerzeile einzulegen.
9. public- und static-Variablen sind zu vermeiden (Seiteneffekte). Stattdessen: set... und get... Methoden deklarieren.

2. Einrückungen

Es sollte mit Tabulatoren (Tab-Taste) eingerückt werden. 4 Leerzeichen sind zur Not auch in Ordnung. Keinesfalls dürfen Tab- und Leerzeicheneinrückungen innerhalb einer Datei gemischt werden.

1. "{" wird hinter die Anweisung geschrieben, die den neuen Anweisungsblock auslöst (ans Zeilenende). "}" wird bündig unter die zugehörige Anweisung geschrieben und steht immer alleine in der Zeile. Bsp.:

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

2. Bei einer neuen Verschachtelungsebene wird eingerückt. Ausnahme: bei case ... wird nicht eingerückt, sondern erst in der darauf folgenden Zeile:

   	switch (condition) {
   	case ...:
   		...
   		break;
   	...
   	default:
   		...
   		break;
   	}
   

3. Nach dem Methodennamen kommt kein Leerzeichen vor die Klammer (bessere visuelle Unterscheidung im Vergleich zu Attributen).
4. Leerzeichen in Ausdrücken sollen die Lesbarkeit erhöhen.
5. Klammerungen können ebenfalls die Lesbarkeit erhöhen und die Fehleranfälligkeit senken.

3. Dokumentation

1. Kommentare vor Klassen/Interfaces/Methoden/Attributen sind mit /** ... */ zu klammern
   • Dokumentation von Attributen: Beschreibung beginnt mit Kleinbuchstaben / Kein Punkt am Ende
2. Dokumentation innerhalb von Methoden sollte mit "//" zeilenweise erfolgen
3. Innerhalb von javadoc kann HTML geschrieben werden!
4. javadoc-Tags können benutzt werden. Z.B.:

   @link	Link setzen
   @see Klassenname	Verweis auf eine andere Klasse, die im javadoc-Kontext sichtbar ist.
   @param Parametername Beschreibung	Parameter von Methoden beschreiben
   @return Beschreibung	Rückgabewert von Methoden beschreiben
   @throws Exceptionname Beschreibung	Mögliche Exceptions beschreiben

1. An den Kopf jeder Datei gehören folgende Informationen (so oder ähnlich):

   	/* ****************************************************************
   	 * Datei:     ....java
   	 * Verfasser: ...
   	 * Version:   1.0
   	 * Datum:     010725
   	 * 
   	 * Letzte Änderungen
   	 *
   	 **************************************************************** */
   

2. Vor jede Klasse/jedes Interface
3. Vor jedes unübliche/trickreiche Mittel

4. Namensgebung

Allgemein: Groß- und Kleinbuchstaben erlaubt / in Ausnahmefällen auch Zahlen. Unterstriche nur in Ausnahmefällen (s.u.). Komponenten zusammengesetzter Namen beginnen mit Grossbuchstaben (Bsp.: diesIstEineVariable). Abkuerzungen sind zu vermeiden. Es sind möglichst aussagekräftige Namen zu benutzen!

1. Pakete, Methoden, Objektattribute, Variablen: erster Buchstabe klein
2. Klassen und Interfaces: erster Buchstabe groß. Die .java-Datei muss exakt wie der Klassenname/Interfacename + ".java" heissen (auf Groß- und Kleinschreibung achten).
3. Klassenkonstanten (static final): Nur Grossbuchstaben, Komponenten zusammengesetzter Namen können durch Unterstriche separiert werden (Unterstriche werden nur zu diesem Zweck eingesetzt)

5. Reihenfolge in Java-Dateien

• Dateikopfzeile
• package-Bezeichnung
• import-Deklarationen
• javadoc kompatibler Kommentar
• Beginn der Klassendeklaration
• statische innere Klassen
• statische Attribute (Klassenattribute)
• static-Initialisierer (Klassenkonstruktor)
• statische Methoden (Klassenmethoden)
• Objektattribute
• Konstruktoren
• Objektmethoden
• innere Klassen
• static void main(String[] args)
• Ende der Klassendeklaration

5.1 Initialisierung von Attributen

5.2. Import-Reihenfolge

1. import-Statements sind alphabetisch aufsteigend sortiert.
2. Es sollen keine Wildcards (z.B. "*") benutzt werden, sondern die benutzten Klassen direkt angeben werden.

6. Interfaces

Implizite Modifizierer von Java werden wiederholt, d.h.

1. Methoden werden explizit als public abstract definiert.
2. Attribute sind public final.
3. Innere Klassen sind public static.

7. Main Methoden

In Main-Methoden stehen kurze Beispiele zur Anwendung der jeweiligen Klasse (und möglichst nur dieser Klasse). Parameter, die der Main-Methode übergeben werden müssen, sind im javadoc-Format zu dokumentieren.

Weitere Quellen zum Thema

1. Offizielle Java Konventionen: http://java.sun.com/docs/codeconv
2. http://www.geosoft.no/javastyle.html