Java Programmierkonventionen

Der Produktkatalog gibt die Nutzung von Maven vor. Daher ist für Anwendungen eine Entwicklung mittels einem oder mehrerer Maven-Module strengstens empfohlen.

Die Sprache von Bezeichnern hängt davon ab, was mit ihnen referenziert wird.

Die Sprache ist eine Mischung aus deutsch und englisch. Für technische Bezeichner wird Englisch verwendet, für fachliche Bezeichner Deutsch. In Bezeichnern werden keine Umlaute und kein ß verwendet.

Beispiele: setMeldung(), suchePerson()

Es sollen möglichst „sprechende“ (selbsterklärende) Namen verwendet werden. Abkürzungen, zum Beispiel durch das Weglassen von Vokalen, sind grundsätzlich zu vermeiden. Ausnahmen dürfen bei temporär verwendeten Variablen (zum Beispiel Zählervariablen in einer for-Schleife) gemacht werden, wenn die Verwendung im Kontext klar ist.

Es sollen nur gängige Bezeichner verwendet werden. Existiert ein Glossar, sind die dort aufgeführten Bezeichner zu verwenden.

Zur besseren Unterscheidung der Namensbestandteile eines Bezeichners wird bei Abkürzungen nur der erste Buchstabe der Abkürzung großgeschrieben.

Das erleichtert die Lesbarkeit, insbesondere wenn zwei Abkürzungen hintereinander folgen.

Es dürfen nicht mehrere Namen verwendet werden, die sich ausschließlich durch abweichende Groß-/Kleinschreibung unterscheiden.

Um Einheitlichkeit bei den Dateinamen sicherzustellen, sind Namenskonventionen für Dateiendungen und gebräuchliche Dateinamen notwendig.

Dateinamen enthalten keine Sonderzeichen, Umlaute oder Leerzeichen. Erlaubt sind die Buchstaben von A bis Z (groß und klein), Ziffern, der Unterstrich, der Mittelstrich und der Punkt. Datumsangaben werden dem Dateinamen vorangestellt und erfolgen im Format <JJJJ-MM-TT_Dateiname>.

In der nachfolgenden Tabelle werden gebräuchliche Dateinamen aufgeführt.

Mehrere Wörter werden bei zusammengesetzten Bezeichnern direkt aneinander geschrieben und nicht durch Sonderzeichen getrennt. Die einzelnen Wörter beginnen jeweils mit einem Großbuchstaben.

Ansonsten gelten die Regeln der nachfolgenden Abschnitte.

Die Package-Struktur folgt einer Konvention, die aus der fachlichen und technischen Referenzarchitektur hergeleitet wird.

Unterhalb von <subsystem/komponente> werden die Packages projektspezifisch strukturiert.

Der Anwendungsname in <anwendung> wird an Java-Package-Konventionen angepasst. Leer- und Sonderzeichen in den Anwendungsnamen werden gestrichen.

Namen von Packages dürfen nur Kleinbuchstaben enthalten.

Bei Klassen- und Interface-Namen wird der erste Buchstabe jedes Teilwortes immer großgeschrieben.

Beispiele: DemoClass, PrintStream, ActionListener

Für die Namen von Klassen sind Substantive zu verwenden.

Beispiel: Meldung

Für Klassen, die Dinge zusammenfassen, soll der Plural verwendet werden.

Beispiele: LineMetrics, Beans, Types, Sachverhalte

Bei Interfaces soll der Bezeichner ein Substantiv oder ein Adjektiv sein. Namen von Interfaces werden NICHT mit dem Präfix „I" versehen.

Besteht der Zweck genau einer Klasse ausschließlich oder zum größten Teil aus der Implementierung eines Interfaces, dann wird die Klasse so genannt wie das Interface, ergänzt um das Suffix Impl.

Beispiele: ActionListener, Runnable, Accessable

Methodennamen sind Verben und beginnen immer mit einem Kleinbuchstaben. Danach wird der erste Buchstabe eines jeden Teilwortes großgeschrieben. Teilworte werden nicht durch Sonderzeichen getrennt, insbesondere nicht durch Unterstriche. Nachfolgende Teilworte können Substantive sein.

Beispiel: doSomething, getStrasse, setName

Die JavaBeans-Konventionen müssen eingehalten werden: Lesen von Eigenschaften mittels getProperty() bzw. isProperty() für Booleans, Schreiben von Eigenschaften mittels setProperty().

Für die Vergabe von Variablennamen gilt: Je globaler die Sichtbarkeit einer Variable ist, desto aussagekräftiger (und ggf. länger) sollte der Name sein. Das schließt nicht aus, das ein für drei Zeilen gültiger Schleifenzähler „i“ heißt.

Variablennamen beginnen immer mit einem Kleinbuchstaben und sind ein Substantiv. Danach wird der erste Buchstabe eines jeden Teilwortes großgeschrieben. Teilworte werden nicht durch Sonderzeichen getrennt.

Beispiel: mySampleVariable

Für die Bezeichner von Sammlungen sind Namen im Plural zu verwenden.

Beispiel: auftraege, auftragsPositionen, kunden

Folgende Bezeichner sind für die Bezeichner von temporären Variablen zu verwenden:

Außer dem Präfix this. bei Instanzvariablen werden keine Präfixe für Klassen-, Instanzvariablen und für Parameter verwendet.

Die Bezeichner von Konstanten werden nur mit Großbuchstaben geschrieben. Jedes Teilwort wird durch einen Unterstrich getrennt. Bei jeder Konstante ist zu überlegen, ob sie nicht durch das Typesafe-Enum-Pattern oder eine Konfigurationsvariable aus einer Datei/Datenbank ersetzt werden kann.

Beispiele: A_MAGIC_NUMBER, MAX_VALUE, MIN_VALUE

Für das Einrücken sind immer vier Leerzeichen zu verwenden. Bei Code-Blöcken wird die öffnende Klammer "{" immer als letztes Zeichen der Zeile gesetzt, die den Code-Block einleitet. Die schließende Klammer "}" wird immer in einer neuen Zeile nach dem Block positioniert und links an dem ersten Zeichen der einleitenden Zeile ausgerichtet.

Zur Einrückung des Textes niemals Tabulatoren, sondern immer Leerzeichen verwenden, da Tabulatoren von verschiedenen Werkzeugen unterschiedlich interpretiert werden können.

Geschweifte Klammern sollen auch dann verwendet werden, wenn innerhalb eines Blocks nur ein Statement vorhanden ist und somit syntaktisch auf deren Verwendung verzichtet werden könnte.

Beispiele für Anwendung der Formatierungsregeln (· steht für ein Leerzeichen):

Es wird empfohlen, Leerzeichen wie folgt zu verwenden:

Leerzeilen eignen sich zur Trennung logischer unabhängiger Teile des Codes. Methoden werden durch eine Leerzeile voneinander getrennt. Auch innerhalb einer Methode können Leerzeilen die logische Trennung von Blöcken verdeutlichen.

Die Zeichen pro Zeile sind auf eine lesbare Anzahl zu begrenzen. Es sollten niemals mehrere Anweisungen in einer Zeile codiert werden. Wenn ein Ausdruck nicht in eine Zeile passt, so ist sie so zu trennen, dass das Ergebnis sinnvoll lesbar ist. Es folgen Hinweise, wo unter Umständen sinnvoll getrennt werden und wie getrennte Zeilen formatiert werden könnten.

Eine Zeile in der Eclipse-Entwicklungsumgebung fasst bei Verwendung der default-Einstellungen ca. 110 Zeichen.

Falls die obigen Regeln zu unleserlichen Einrückungen führen, wird der Code um acht Zeichen eingerückt.

Das Umbrechen einer Zeile geschieht möglichst nach einem Komma. Die nächste Zeile wird dann an dem Ausdruck vor dem Komma ausgerichtet.

Prinzipiell müssen alle Klassen, Interfaces und Methoden einen Dokumentationskommentar (eine Außensicht) enthalten. Ausnahmen sind im Einzelfall anonyme innere Klassen und ihre Methoden sowie Implementierungsklassen von Interfaces (dort mit @see auf die Interface-Dokumentation verweisen). Es wird empfohlen, je Package eine Datei package-info.java zu erzeugen, die das Zusammenspiel von Klassen/Interfaces in dem Package erläutert.

Für die Erstellung von Dokumentationskommentaren gelten die folgenden Regeln:

Beispiel:

Javadoc verwendet den ersten Satz in einer Beschreibung als Kurzbeschreibung des zu dokumentierenden Elements (Klasse, Schnittstelle, Methode, Attribut).

Jeder Parameter einer Methode wird mit einem @param-Tag beschrieben. Das @return-Tag wird nur verwendet, wenn der Rückgabewert der Methode ungleich void ist. Jede checked Exception, die in der throws-Klausel der Methode aufgeführt ist, wird mit einem @exception-Tag kommentiert.

Beispiel:

Kommentare zu Attributen sehen zum Beispiel wie folgt aus:

@see-Tags sind sparsam zu verwenden, denn diese Verlinkung muss manuell gepflegt werden. Mehrere @see-Tags werden gemäß ihrer "Entfernung" von der aktuellen Stelle aufgeführt (Dokumenten-Navigation, Namensqualifikation). Innerhalb einer Gruppe überladener Methoden werden die Methoden gemäß der Anzahl Parameter aufgelistet.

Beispiel:

@inheritDoc sollte nur genutzt werden, wenn beim Überschreiben der Methode weitere Informationen im Javadoc gegenüber dem Parent ergänzt werden. Wenn die überschreibende Methode keine zusätzlichen Informationen im Javadoc mitgegeben bekommt, kann @inheritDoc weggelassen werden. Javadoc kopiert automatisch die Beschreibung des Parents, wenn keine Beschreibung angegeben wird.

Autoren (und damit Verantwortlichkeiten für Bestandteile des Quellcodes) sowie Details über die aktuelle Version werden über das verwendete Versionskontrollsystem ermittelt.

Code sollte immer selbsterklärend geschrieben werden und möglichst wenige Inline-Kommentare enthalten. Implementierungskommentare begründen Designentscheidungen, die aus dem Code nicht allein ersichtlich sind, oder sie erklären aufwändige Algorithmen. Sie wiederholen nicht den Code in Prosa (Negativbeispiel: "Erhöhe Schleifenzähler um 1"). Implementierungskommentare werden für folgende Zwecke eingesetzt:

Wenn eine Stelle im Code noch nicht fertig ist und später kontrolliert oder überarbeitet werden soll, so ist sie mit // TODO: Grund zu markieren. Einige Entwicklungsumgebungen wie z. B. Eclipse und IntelliJ zeigen diese speziellen Kommentare analog zu Fehlern in einer To-do-Liste an. Alle Kommentare sind in Englisch zu verfassen.

Es wird immer der Ist-Zustand beschrieben. Änderungen werden in der Änderungshistorie beschrieben. Kommentare werden nicht dazu verwendet, alte Versionen des Codes zu deaktivieren. Wenn man alte Versionen wiederherstellen möchte, so ist dazu auf das Konfigurationsmanagement zurückzugreifen. Für die Analyse von Codeänderungen sind die bekannten DIFF-Werkzeuge einzusetzen.

Änderungen werden mittels eines Version Control System (z. B. Subversion) nachverfolgt. Dazu ist es zwingend erforderlich, die durchgeführten Änderungen bzw. die Ursache dafür beim Check-in ausreichend zu dokumentieren. Die Dokumentationssprache hierfür ist deutsch. Darüber hinaus werden keine Versionsinformationen im Source Code gepflegt.

Import-Statements werden nach Packages sortiert und gruppiert. Folgende Import-Statements sind zu vermeiden:

Seit Java 1.5 gibt es eine Kurzschreibweise für verschiedene Programmierkonstrukte (z. B. Bedingungen, Schleifen). Folgende Kurzschreibweisen sind erlaubt:

und

Letzteres ist erlaubt, sollte aber vermieden werden.

Nicht erlaubt ist die Kurzschreibweise für Bedingungen, also das Weglassen der Klammern:

Alle Klassen leiten sich von der Basisklasse Object ab und erben von dieser die Methoden equals(), hashCode(), toString(), clone() und finalize(). Diese Methoden sind bewusst als non-final Methoden angelegt, damit sie klassenspezifisch angepasst werden können.

Die von der Klasse Object vererbte Implementierung für die Methoden equals() und hashCode() stellt nur eine Basisimplementierung dar, die für alle Klassen genügt, deren Identität auf Objektgleichheit (gleiche Speicheradresse) basiert. Klassen, die eine eigene Identität, unabhängig von der Objektgleichheit, besitzen, müssen equals() und hashCode() implementieren. Dabei können leicht schwer identifizierbare Fehler auftreten. Die Implementierung von equals() und hashCode() ist nicht trivial, da sie bestimmte Eigenschaften (Reflexivity, Symmetry, Transitivity, Consistency und Non-nullity erfüllen müssen (siehe auch "Effective Java Second Edition" (Bloch, 2008) ).

Zur Implementierung von equals() und hashCode() müssen die Möglichkeiten der Hilfsklasse java.util.Objects verwendet werden, insbesondere die Methoden: