home  |  suche  |  kontakt/johner  |  institut 
studierende  |  tech-docs  |  mindmailer 

Einleitung

Die folgenden Abschnitte beschreiben die wichtigsten Regeln, die dazu dienen sollen, den Code

     

  • wartbarer zu gestalten (änderbar, wiederverwendbar)
  • für andere lesbar und verstehbar zu machen
  • fehlerfreier zu schreiben

Es empfiehlt sich ein Blick auf die "offiziellen" Java Code Conventions bzw. deren deutsche Übersetzung.

Aufbau einer Javaklasse

Die folgend beschriebene Reihenfolge sollte beim Aufbau einer Javaklasse eingehalten werden. Teilweise wird sie bereits durch den Compiler erzwungen:

     

  • Optionaler Kommentar mit Version, Datum, Autor
  • Package
  • Import-Statements
  • Konstanten/statische Klassenvariablen
  • Instanzvariablen
  • Konstruktoren
  • Methoden

Innerhalb der Methoden sollte die logische Reihenfolge eingehalten werden (z.B. Hilfsmethode in Nähe der sie aufrufenden Methode) und nicht nach privaten und öffentlichen (public) Methoden getrennt werden.

 

TODO: Beispiel für korrekt formatierte Klasse

TODO: Verweis auf Erzeugung von JavaDocs mit Eclipse

Namenskonventionen

Auch wenn Java dem Entwickler viele Freiheiten in Bezug auf die Namensgebung von Klassen, Variablen und Methoden gibt, empfiehlt SUN dennoch folgende Konventionen einzuhalten:

     

  • Klassennamen beginnen mit einem Großbuchstaben und stellen ein Substantiv dar. Falls ein zusammengesetztes Wort gewählt wird, schreibt man die ersten Buchstaben ebenfalls groß: Beispiele: Student, StudentFactory, IndexOutOfBoundsException
  • Die Namen von Packages bestehen nur aus Kleinbuchstaben
  • Methodennamen werden klein geschrieben, man bevorzugt Verben. Beispiele: createStudent(), getName()
  • Bei Instanzvariablen wird ebenfalls der erste Buchstabe klein geschrieben, auch hier sollten sinnvolle Namen genutzt werden. Beispiele: student, aStudent, bestStudent und nicht kryptische Abkürzungen (bstStdnt). Eine Ausnahme bilden die Schleifenzähler (i, j, k ...)
  • Konstanten (static) bestehen nur aus Großbuchstaben und dem Unterstrich (_), der jedoch nicht das erste Zeichen bilden darf. Beispiele: COPYRIGHT, NUMBER_DAYS, TABLE_NAME
  • Mit Ausnahme des Unterstriches bei (und nur bei) Konstanten sollten alles Sonderzeichen vermieden werden

Formatierung

Ebenfalls in den Java Code Conventions beschrieben sind einige Regeln zur Formatierung des Quellcodes:

     

  • Keine Leerzeichen nach Methodennamen, aber vor und nach Schlüsselworten und Operatoren (for, while, +, ...)
  • Jedes Statement in eine eigene Zeile
  • Keine Mehrfachdeklarationen in einer Zeile (also nicht int a, b;)
  • Bei Kontrollstrukturen (for, if, while, ..) immer Klammern ({..}) nutzen
  • Geklammerte Abschnitte hierarchisch einrücken

Dokumentation

Die Dokumentation wird generell meist vernachlässigt. Dies umfasst nicht nur die nachfolgend beschriebene Dokumentation Quellcodes, sondern auch die Entwicklerdokumentation, Dokumentation von Tests, Benutzerhandbücher und vieles mehr.

Die Quellcode-Dokumentation unterscheidet JavaDocs und die "Inline"-Kommentare.

JavaDocs

     

  • beginnen mit /** und enden mit */
  • sind für jede Klasse, jeden Konstrutor, für jede (nicht-triviale) Methode und jede Klassen- und Instanzvariable zu schreiben
  • kennzeichnen Übergabeparameter mit @param
  • kennzeichnen geworfene Exceptions mit @throws
  • kennzeichnen Rückgabewerte mit @return
  • Nutzen HTML-Tags zur Strukturierung des Codes. Diese sollten sich aber auf <b>, <i>, <ul>, <ol>, <li> beschränken. Insbesondere sind die Überschriftentags <h1>, <h2> usw genauso wie Formatierungen (<font> etc.) zu vermeiden.

Beispiel

 

/**
* Diese Methode demonstriert JavaDoc
* @param zahl Zahl, deren Quadrat berechnet werden soll
* @return das Quadrat der Zahl
* @throws IllegalArgumentException Fehler, der geworfen wird,
* wenn die Zahl groesser als 2^8 ist
*/
public int berechneQuadrat(int zahl) throws IllegalArgumentException {
..
}

 

Bei der Beschreibung von Klassen und Methoden mit JavaDoc kommt es darauf an, deren Aufgabe inhaltlich zu beschreiben, und nicht, den Quellcode schrittweise zu erläutern.

Die zweite Form des Kommentierens sind die Inline-Kommentare (//..). Sie erläutern kurz, was die Aufgabe der Zeile(n) ist, weshalb sie so geschrieben wurden und was möglicherweise noch zu tun ist (TODO).

Aus den JavaDocs lässt sich eine übersichtliche Dokumentation der API schaffen, wie man es von der Java-API kennt.

Metriken

Die hier gelisteten Metriken bilden zwar nur eine kleine Teilmenge der von Checkstyle überprüften Größen, jedoch enthält diese Auflistungen viele der wichtigsten.

     

  • Dateigröße < 2000 Zeilen
  • Zeilenlänge < 80 Zeichen (ich halte 120 Zeichen für akzeptabel)
  • Methodenlänge < 150 Zeilen (muss auf jeden Fall auf einer Bildschirmseite ohne Scrollen lesbar sein
  • Die Anzahl der Übergabeparameter auf 7 beschränken (andernfalls Klasse übergeben, welche die Parameter enthält
  • Anzahl logischer Operatoren (&&, ||) pro Statement <= 3
  • Schachtelungstiefe <= 3
  • Zyklomatische Komplexität (Mc Cabe-Maß)