Programmierstil

Code-Dokumentation

Man verwendet Kommentare, um den Sinn und Zweck von Codezeilen direkt an Ort und Stelle zu dokumentieren und zu beschreiben. Kommentare werden durch spezielle Zeichen eingeleitet, die dem Compiler mitteilen, dass die nachfolgenden Wörter nicht als Code interpretiert werden sollen. Mit einem doppelten Slash (//) leitet man einen Kommentar bis zum Zeilenende ein. Das bedeutet, dass alles, was nach dem doppelten Slash steht, nicht als Quellcode interpretiert wird. Einzeilige Kommentare werden verwendet, um besonders kurze Beschreibungen zu hinterlassen.

Beschreibungen, die aus mehreren Zeilen bestehen, werden besser über geklammerte Kommentare eingeleitet. Diese werden mit Slash und Stern (/*) angefangen und mit Stern und Slash (*/) beendet. Alles zwischen diesen beiden Zeichenkombinationen wird nicht als Quellcode interpretiert.

Geklammerte Kommentare werden verwendet, um längere Erklärungen direkt im Code zu hinterlassen. Sie werden beispielsweise für die Dokumentation von Klassen, Attributen und Methoden verwendet. Klassenkommentare beschreiben den Zweck einer Klasse, unter welchen Umständen sie verwendet werden kann und was man bei der Vererbung beachten sollte. Attributkommentare beschreiben die Bedeutung eines Attributs für die Klasse. Methodenkommentare dokumentieren, was der Zweck der Methode ist, was die Parameter der Methode bedeuten und was die Methode unter welchen Voraussetzungen zurückgibt.

Über die Zeit hat sich diese Art der Dokumentation etabliert, sodass ein Standard vereinbart wurde, der die Beschreibung von Funktionalitäten, Parametern und dergleichen geeignet formalisiert. Der Standard definiert eindeutige Schlüsselwörter, die von einem externen Programm namens Javadoc automatisch für die technische Dokumentation verwendet werden können. Für die Dokumentation mit Javadoc sind ein paar Voraussetzungen zu erfüllen. Nur geklammerte Kommentare werden für die automatische Generierung der Dokumentation verarbeitet. Sie müssen mit einem Slash und zwei nachfolgenden Sternen (/**) eingeleitet werden. Der erste Satz eines Kommentars stellt die Kurzbeschreibung der Klasse, des Attibuts oder der Methode dar. Hier soll der Zweck so kurz wie möglich beschrieben werden. Alle folgenden Sätze können für die ausführliche Beschreibung verwendet werden. Da Javadoc schlussendlich HTML-Seiten erstellt, darf in der ausführlichen Beschreibung auch HTML-Quellcode verwendet werden. Bei der Beschreibung von Methoden stehen Schlüsselwörter in Form von Javadoc-Tags zur Verfügung, die grundsätzlich mit einem @ beginnen:

• @param wird für die Beschreibung eines Methoden-Parameters verwendet. Für jeden Parameter wird ein eigenes @param-Schlüsselwort verwendet.
• @return wird verwendet, um zu beschreiben, was die Methode unter welchen Umständen zurückgibt.
• @throws führt mögliche Fehlerquellen auf und die Exceptions, die dabei geworfen werden. Pro möglicher Exception wird ein @throws verwendet.

Javadoc lässt sich aus Eclipse aufrufen. Im Menü "Project" bedindet sich der Eintrag "Generate Javadoc", mit dem die automatische Umwandlung angestoßen werden kann. Standardmäßig wird die erzeugte Dokumentation im Projekt-Unterordner doc erstellt. Die einzelnen Dokumente sind nach Klassen eingeordnet und auch miteinander verlinkt, falls zum Beispiel eine Vererbungsbeziehung zwischen ihnen besteht.

Code-Annotationen

Bei Meta-Informationen handelt es sich um zusätzliche Details zum Quellcode, die Aussagen über den Code machen. Zum Beispiel kann dem Compiler gesagt werden, wenn es sich bei einer Methode um eine überschriebene Methode handelt, sodass dies vom Compiler noch einmal explizit überprüft werden kann. Damit dem Java-Compiler diese Meta-Informationen bekannt gemacht werden können, wurden ab der Java-Version 1.6 die sogenannten Annotationen eingeführt.

Annotationen beginnen immer mit einem @-Zeichen. Man kann Klassen, Attribute und Methoden annotieren, indem man die Annotation über die jeweilige Deklaration schreibt. Die zwei geläufigsten Annotationen sind @Override und @Deprecated.

• Mittels @Override kennzeichnet man Methoden, die überschrieben wurden. Der Compiler bricht mit einem Fehler ab, falls die so annotierte Methode keine andere Methode überschreibt.
• Mittels @Deprecated kennzeichnet man Klassen, Attribute und Methoden, die veraltet sind und in neuem Code nicht mehr verwendet werden sollen. Diese Annotation löst in Code, der diese Codeteile benutzt, eine Warnung aus.

Code-Konventionen

Es kommt vor, dass man Code verändern muss, der von anderen Programmierern geschrieben wurde. Genauso wahrscheinlich ist es, dass man selber Code schreibt, der von anderen Leuten benutzt oder verändert wird. Hier lohnt es sich, etablierte Konventionen zur Strukturierung, Benennung und Formatierung von Code zu beachten, damit jeder Programmierer sich schneller in bestehendem Quellcode zurechtfindet.

Code-Konventionen wirken sich meist auf die Strukturierung von Code, die Benennung von Variablen oder die Formatierung von Quelltext aus. Kurz gesagt, Code-Konventionen stellen grundsätzliche Regeln auf, die das Lesen und Verstehen von Quelltext vereinfachen sollen. Diese Regeln wirken sich nicht auf die Funktionalität der Software aus, sie werden auch nicht vom Compiler überprüft. Sie dienen den Menschen, die den Code lesen, verstehen und bearbeiten sollen. Je klarer der Code formuliert ist, desto einfacher kann ein Programmierer über die Konsequenzen des Codes nachdenken und desto sicherer kann er dann Veränderungen daran vornehmen.

Für die Benennung von Code haben sich die folgenden Konventionen etabliert:

• Paketnamen werden stets klein geschrieben.
• Klassen und Interfaces werden als Substantive benannt und stets mit einem großen Anfangsbuchstaben geschrieben. Besteht ein Klassenname aus mehreren Wörtern, so werden die einzelnen Wortanfänge ebenfalls großgeschrieben. Man spricht auch von Camel-Case, weil der zusammengesetzte Name durch die Groß- und Kleinschreibung "Buchstabenhöcker" bekommt.
• Klassenkonstanten werden komplett großgeschrieben und Wörter mit Unterstrich voneinander getrennt.
• Methodennamen sind möglichst immer Verben. Sie werden mit kleinem Anfangsbuchstaben, aber sonst in Camel-Case geschrieben.
• Attribute und Variablen sollen sinnvoll benannt sein, sodass sich aus dem Namen bereits eine Beschreibung des Inhalts schließen lässt.

Im Allgemeinen sollte bei der Strukturierung von Code darauf geachtet werden, dass zusammengehörige Dinge auch nahe beieinander stehen sollen. Für den Aufbau von Klassen gibt es die Konvenion, erst alle Attribute der Klasse aufzuführen, bevor die Methoden geschrieben werden.

Die folgende Abbildung fasst zusammen, in welcher Reihenfolge die Elemente einer Klasse typischerweise angegeben werden:

Um die Lesbarkeit von Code-Blöcken zu erhöhen ist es wichtig, deutlich zu machen, wo ein Code-Block anfängt und wo er aufhört. Dies wird durch eine geeignete Formatierung der zugehörigen geschweiften Klammern erreicht. Ob die beginnende geschweifte Klammer an das Ende einer Zeile oder in eine neue Zeile gesetzt wird, ist weniger wichtig, als dass die richtige Einrückung eingehalten wird. Dies gilt sowohl für den umschlossenen Code als auch die schließende Klammer. Auf diese Weise erkennt ein anderer Programmierer auf einen Blick, wo eine Methode, ein if-Block oder ein Schleifenrumpf beginnt und aufhört.

Der Aufbau von Code-Blöcken unterliegt weiteren Konventionen:

• Benötigte Variablen sollten zu Beginn eines Blocks deklariert und gleichzeitig initialisiert werden.
• Jede Deklaration wird in eine eigene Zeile geschrieben.
• Leerzeilen werden verwendet, um semantisch zusammenhängende Anweisungsabschnitte voneinander zu trennen.
• Leerzeichen hingegen trennen semantische Einheiten innerhalb einer Codezeile. Das bedeutet, sie trennen die Operanden eines Ausdrucks, werden aber nicht zwischen den Methodennamen und dessen Klammer oder das for, if oder while und dessen Klammer gsetzt.