Information

An dieser Website wird noch gearbeitet. Keine Garantie für Funktionalität und Inhalt!

Pro­gram­mier­stil

Die Codeconventions des HCJ-Website-Builders für gut verständlichen und einheitlichen Code.

Ver­sion 0.3.0

Vgl. Github.

§1 Vor­wort

Diese Code Conventions sind Grundlage aller im FG-Team entstehenden Codeteile der Programmiersprache Java. Sie sollen dem Code eine feste Struktur geben und so dessen Qualität sichern. Alle Entwickler des FG-Teams verpflichten sich mit dem Beitritt dazu, ihre Codeteile nach bestem Wissen an dieser Konvention auszurichten. Des Weiteren verpflichten sie sich, bei der Suche nach Unstimmigkeiten im Bezug auf Regeln der verwendeten Programmiersprache und dieser Konvention den zu prüfenden Codeteil genauestens unter die Lupe zu nehmen. Sollten Sie in diesen Konventionen fehlende Erläuterungen zu bestimmten Situationen oder Fehler/Widersprüchlichkeiten finden, so melden Sie dies über die bekannten Kommunikationswege, damit alle Beteiligten hierzu einen Nachtrag in diese Konventionen einbringen können.

§2 Ge­ne­rel­le Be­mer­kun­gen

In diesem Abschnitt folgen generelle Bemerkungen, die für alle Codeebenen (Klassen/Interfaces, Methoden, Attribute und/oder Anweisungen) gelten.
  1. Es sind eindeutige, englischsprachige Bezeichner zu verwenden, sodass deren Bedeutung sich (zumindest grob) herleiten lässt.
  2. Abkürzungen sind zu vermeiden.
    1. Zulässige Abkürzungen sind Buchstaben als Schleifenvariablen.
    2. Eine zulässige Abkürzung ist auch cls als Bezeichner eines Class-Objektes, da class ein Schlüsselwort ist.
  3. Javadoc-Kommentare enthalten alle zutreffenden Schlüsselwörter. D. h., dass alle Schlüsselwörter, die auf einen Bestandteil zu beziehen sind, in dessen Dokumentation aufgeführt werden.
  4. Die erste Zeile eines Javadoc-Kommentars (beginnend mit /**) beinhaltet eine Kurzbeschreibung des jeweiligen Bestandteils, die mit einem Punkt abgeschlossen wird.
  5. Ein Javadoc-Kommentar enthält keine Leerzeilen.
  6. Das Kommentarende */ steht in einer separaten Zeile ohne sonstigen Inhalt.
  7. Alle zutreffenden Annotations müssen angegeben werden, insbesondere @Override.
  8. Keine Codezeile darf länger als 80 Zeichen sein.
  9. Eine Einrückung entspricht vier einzelnen Leerzeichen.
    1. Sollte damit eine Einrückung zu der gewollten Position nicht möglich sein, so muss bis zum ersten Einrückpunkt hinter dieser Position eingerückt werden. Keinesfalls dürfen ein bis drei Leerzeichen eingesetzt werden, um Teile exakt untereinander zu bringen.
  10. Der erstellte Code darf weder zu Fehlermeldungen noch zu Warnungen des Compilers führen.
    1. Das Unterdrücken von Fehlern und Warnungen (vor allem die Verwendung der Annotation @SuppressWarnings) ist begründet zu dokumentieren.
  11. Geschweifte Klammern stehen stets in einer eigenen Zeile. Ggf. dürfen Zeilenkommentare (jedoch keine Blockkommentare!) folgen.
  12. Ein Block (i. d. R. begrenzt durch geschweifte Klammern {}) ist stets einmal mehr eingerückt als der ihm übergeordnete Block.
  13. Grunddatentypen dürfen nicht verwendet werden. Stattdessen stehen für die Speicherung von Werten Objekte der Wrapper-Klassen zur Verfügung.

§3 Klas­sen und In­ter­fa­ces

  1. Klassen- und Interfacenamen beginnen stets mit FG (in dieser Schreibweise).
  2. Über jeder Klasse und jedem Interface steht ein Javadoc-Kommentar.
  3. Dieser Javadoc-Kommentar enthält die Namen sämtlicher Autoren, die zu dieser Klasse maßgeblich beigetragen haben.
  4. Eine Klassendeklaration hat die Form class X<T> extends Y<U> implements Z, ZZ.
  5. Ein Zeilenumbruch ist an folgenden Stellen erlaubt, wobei die kleinste Zahl zur größten Priorität gehört:
    1. Kein Umbruch.
    2. Nach der extends Klausel.
    3. Sowohl nach der class, als auch nach der extends Klausel.
  6. Die Klassenbestandteile sind in folgender Reihenfolge anzuordnen:
    1. Statische Attribute
    2. Instanzattribute
    3. Statische Konstruktoren
    4. Instanzkonstruktoren
    5. Statische Methoden
    6. Instanzmethode
  7. Die Elemente sollten nach Inhalt sortiert werden. Dies dient allerdings nur der Übersichtlichkeit und erfolgt nach weniger strengen Regeln.
    Die Grundprinzipien sind:
    1. Die Elemente werden nach dem (voraussichtlichen) Verwendungszeitpunkt sortiert.
    2. Methoden, die an einem gemeinsamen Attribut arbeiten (z. B. getter und setter), stehen zusammmen.
    3. Methoden mit gleicher Bezeichnung werden nach Anzahl und Typ der Parameter sortiert.
  8. Die serialVersionUID einer Klasse, soweit notwendig, ist bei einer Änderung, die die Klasse inkompatibel zu vorherigen Versionen macht, wie folgt mit dem aktuellen Zeitpunkt zu kennzeichnen: private final static long serialVersionUID = TTMMJJJJHHMinMinSS (02.01.2014 15:00:30 -> 02012014150030).

§4 At­tri­bu­te

  1. Der Wert öffentlicher Konstanten muss dokumentiert werden.
  2. Attribute eines Interfaces sind als final static zu kennzeichnen, obgleich sie diese Eigenschaften durch das Interface verliehen bekommen.

§5 Me­tho­den

  1. Über jeder Methode steht ein Javadoc-Kommentar.
  2. Annotations zu einer Methode stehen in der Zeile direkt über der Methode.
  3. Eine Methodendeklaration hat die Form <T> public int getCount(T object) throws Exception1.
  4. Ein Zeilenumbruch ist an folgenden Stellen erlaubt, wobei die kleinste Nummer zur größten Priorität gehört:
    1. Kein Umbruch.
    2. Nach dem Klammerpaar ().
    3. Nach dem Methodenbezeichner (hier: getCount), also vor dem Klammerpaar ();
    4. Nach der öffnenden Klammer ( sowie nach jedem Parameter. Die schließende Klammer ) steht dann hinter dem letzten Parameter.
  5. Das Klammerpaar () steht ohne Leerzeichen direkt hinter dem Methodenbezeichner.
  6. Eine als @deprecated markierte Methode darf nicht aufgerufen werden.
  7. Methoden eines Interfaces sind als abstract zu kennzeichnen, obgleich sie diese Eigenschaften durch das Interface verliehen bekommen.
  8. Eine Methode besitzt genau eine return Anweisung.
  9. Es darf beliebig viele throw Anweisungen geben.
  10. Jede Methode führt die Klassen aller Exceptions, die sie werfen kann, in ihrer throws Klausel auf (auch RuntimeException + Unterklassen).

§6 An­wei­sun­gen

  1. Bei Bezug auf Klassenelemente in Anweisungen müssen die Zeiger this und super dem Elementbezeichner vorangestellt werden.
  2. Switch-Anweisung:
    1. Der Bereich zwischen zwei case Anweisungen zählt als Block und wird entsprechend behandelt.
    2. Sollten hinter allen case Anweisungen eines switch-Blockes nur eine Codezeile (inklusive break) folgen, so dürfen die Anweisungen hinter das case notiert werden.
    3. Vor und nach dem Doppelpunkt der case-Anweisung befindet sich jeweils ein Leerzeichen.
    4. Wenn ein case-Block nicht mit einem break endet, so ist dies mit dem Zeilenkommentar //continue with next case kenntlich zu machen.
  3. If-else-Anweisung:
    1. Jedes else [if] in neue Zeile, nicht hinter schließende Klammer des letzten Blocks
  4. Kurzformoperator Prüfungsausdruck ? WertWennWahr : WertWennFalsch
    1. Dieser Operator darf nicht verwendet werden, da er schwierig zu lesen ist.

§7 An­hang

Anmerkungen (Fußnoten)

  1. Die Formdefinitionen enthalten bewusst Generics, um deren Stellung zu definieren. Diese können in vielen Fällen ignoriert werden.
  2. Diese Methode bleibt allerdings im Quelltext stehen, damit Abwärtskompatibilität zu vor der Kennzeichnung geschriebenen Codeteilen besteht. Ist dies nicht gewünscht, so müssen vor der Löschung alle Codeteile, die diese Methode aufrufen, umgeschrieben werden.

Kurz­fas­sung der Code Con­ven­tions

  1. Generell
    1. Sinnvolle Bezeichner ohne Abkürzungen
    2. Vollständige Javadoc-Kommentare
    3. Annotations angeben
    4. Zeilenlänge <= 80 Zeichen
    5. Einrückung = 4 Zeichen
    6. Keine Fehlermeldungen und Warnungen
    7. Eigene Zeile für { und }
    8. Keine primitiven Datentypen
    9. Blockeinrückung
  2. Klassen/Interfaces
    1. Präfix FG
    2. Javadoc
    3. Elemente sortieren
  3. Methoden
    1. Javadoc
    2. Annotations
    3. Keine deprecated-Methoden aufrufen
    4. Im Interface: abstract
    5. return-Anweisungen
  4. Attribute
    1. Öffentliche Konstanten dokumentieren
    2. Im Interface: final static
  5. Anweisungen
    1. Zeiger this, super
    2. switch: case ist Block; Fortsetzung im nächsten case-Block dokumentieren
    3. if-else: jedes else [if] in neue Zeile
    4. Kurzformoperator ...?...:... nicht verwenden

Change­log

Versionsnummer Änderungen
0.1.0 Erste Version.
0.1.1 §1 Abs. 1 geändert (Programmiersprache Java), §3 Abs. 2a eingefügt.
0.1.2 §5 Abs. 8 geändert.
0.2.0 Viele Details geändert, in HTML umgewandelt.
0.2.5 In Layout der Webite jonas-thelemann.de gebracht.
0.3.0 Rechtschreibfehler korrigiert, Layout weiter optimiert.
0.3.1 Grammatik verbessert.