Programmierstil
Die Codeconventions des HCJ-Website-Builders für gut verständlichen und einheitlichen Code.
Version 0.3.0
Vgl. Github.§1 Vorwort
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 Generelle Bemerkungen
In diesem Abschnitt folgen generelle Bemerkungen, die für alle Codeebenen (Klassen/Interfaces, Methoden, Attribute und/oder Anweisungen) gelten.- Es sind eindeutige, englischsprachige Bezeichner zu verwenden, sodass deren Bedeutung sich (zumindest grob) herleiten lässt.
-
Abkürzungen sind zu vermeiden.
- Zulässige Abkürzungen sind Buchstaben als Schleifenvariablen.
-
Eine zulässige Abkürzung ist auch
cls
als Bezeichner eines Class-Objektes, daclass
ein Schlüsselwort ist.
- 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.
-
Die erste Zeile eines Javadoc-Kommentars (beginnend mit
/**
) beinhaltet eine Kurzbeschreibung des jeweiligen Bestandteils, die mit einem Punkt abgeschlossen wird. - Ein Javadoc-Kommentar enthält keine Leerzeilen.
-
Das Kommentarende
*/
steht in einer separaten Zeile ohne sonstigen Inhalt. -
Alle zutreffenden Annotations müssen angegeben werden, insbesondere
@Override
. - Keine Codezeile darf länger als 80 Zeichen sein.
-
Eine Einrückung entspricht vier einzelnen Leerzeichen.
- 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.
-
Der erstellte Code darf weder zu Fehlermeldungen noch zu Warnungen des Compilers führen.
-
Das Unterdrücken von Fehlern und Warnungen (vor allem die Verwendung der Annotation
@SuppressWarnings
) ist begründet zu dokumentieren.
-
Das Unterdrücken von Fehlern und Warnungen (vor allem die Verwendung der Annotation
- Geschweifte Klammern stehen stets in einer eigenen Zeile. Ggf. dürfen Zeilenkommentare (jedoch keine Blockkommentare!) folgen.
-
Ein Block (i. d. R. begrenzt durch geschweifte Klammern
{}
) ist stets einmal mehr eingerückt als der ihm übergeordnete Block. - Grunddatentypen dürfen nicht verwendet werden. Stattdessen stehen für die Speicherung von Werten Objekte der Wrapper-Klassen zur Verfügung.
§3 Klassen und Interfaces
-
Klassen- und Interfacenamen beginnen stets mit
FG
(in dieser Schreibweise). - Über jeder Klasse und jedem Interface steht ein Javadoc-Kommentar.
- Dieser Javadoc-Kommentar enthält die Namen sämtlicher Autoren, die zu dieser Klasse maßgeblich beigetragen haben.
-
Eine Klassendeklaration hat die Form
class X<T> extends Y<U> implements Z, ZZ
. -
Ein Zeilenumbruch ist an folgenden Stellen erlaubt, wobei die kleinste Zahl zur größten Priorität gehört:
- Kein Umbruch.
-
Nach der
extends
Klausel. -
Sowohl nach der
class
, als auch nach derextends
Klausel.
-
Die Klassenbestandteile sind in folgender Reihenfolge anzuordnen:
- Statische Attribute
- Instanzattribute
- Statische Konstruktoren
- Instanzkonstruktoren
- Statische Methoden
- Instanzmethode
-
Die Elemente sollten nach Inhalt sortiert werden.
Dies dient allerdings nur der Übersichtlichkeit und erfolgt nach weniger strengen Regeln.
Die Grundprinzipien sind:- Die Elemente werden nach dem (voraussichtlichen) Verwendungszeitpunkt sortiert.
- Methoden, die an einem gemeinsamen Attribut arbeiten (z. B. getter und setter), stehen zusammmen.
- Methoden mit gleicher Bezeichnung werden nach Anzahl und Typ der Parameter sortiert.
-
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 Attribute
- Der Wert öffentlicher Konstanten muss dokumentiert werden.
-
Attribute eines Interfaces sind als
final static
zu kennzeichnen, obgleich sie diese Eigenschaften durch das Interface verliehen bekommen.
§5 Methoden
- Über jeder Methode steht ein Javadoc-Kommentar.
- Annotations zu einer Methode stehen in der Zeile direkt über der Methode.
-
Eine Methodendeklaration hat die Form
<T> public int getCount(T object) throws Exception1
. -
Ein Zeilenumbruch ist an folgenden Stellen erlaubt, wobei die kleinste Nummer zur größten Priorität gehört:
- Kein Umbruch.
-
Nach dem Klammerpaar
()
. -
Nach dem Methodenbezeichner (hier:
getCount
), also vor dem Klammerpaar()
; -
Nach der öffnenden Klammer
(
sowie nach jedem Parameter. Die schließende Klammer)
steht dann hinter dem letzten Parameter.
-
Das Klammerpaar
()
steht ohne Leerzeichen direkt hinter dem Methodenbezeichner. -
Eine als
@deprecated
markierte Methode darf nicht aufgerufen werden. -
Methoden eines Interfaces sind als
abstract
zu kennzeichnen, obgleich sie diese Eigenschaften durch das Interface verliehen bekommen. -
Eine Methode besitzt genau eine
return
Anweisung. -
Es darf beliebig viele
throw
Anweisungen geben. -
Jede Methode führt die Klassen aller Exceptions, die sie werfen kann, in ihrer
throws
Klausel auf (auchRuntimeException
+ Unterklassen).
§6 Anweisungen
-
Bei Bezug auf Klassenelemente in Anweisungen müssen die Zeiger
this
undsuper
dem Elementbezeichner vorangestellt werden. -
Switch-Anweisung:
-
Der Bereich zwischen zwei
case
Anweisungen zählt als Block und wird entsprechend behandelt. -
Sollten hinter allen
case
Anweisungen eines switch-Blockes nur eine Codezeile (inklusivebreak
) folgen, so dürfen die Anweisungen hinter dascase
notiert werden. - Vor und nach dem Doppelpunkt der case-Anweisung befindet sich jeweils ein Leerzeichen.
-
Wenn ein case-Block nicht mit einem break endet, so ist dies mit dem Zeilenkommentar
//continue with next case
kenntlich zu machen.
-
Der Bereich zwischen zwei
-
If-else-Anweisung:
-
Jedes
else [if]
in neue Zeile, nicht hinter schließende Klammer des letzten Blocks
-
Jedes
-
Kurzformoperator Prüfungsausdruck ? WertWennWahr : WertWennFalsch
- Dieser Operator darf nicht verwendet werden, da er schwierig zu lesen ist.
§7 Anhang
Anmerkungen (Fußnoten)
- Die Formdefinitionen enthalten bewusst Generics, um deren Stellung zu definieren. Diese können in vielen Fällen ignoriert werden.
- 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.
Kurzfassung der Code Conventions
-
Generell
- Sinnvolle Bezeichner ohne Abkürzungen
- Vollständige Javadoc-Kommentare
- Annotations angeben
- Zeilenlänge <= 80 Zeichen
- Einrückung = 4 Zeichen
- Keine Fehlermeldungen und Warnungen
-
Eigene Zeile für
{
und}
- Keine primitiven Datentypen
- Blockeinrückung
-
Klassen/Interfaces
-
Präfix
FG
- Javadoc
- Elemente sortieren
-
Präfix
-
Methoden
- Javadoc
- Annotations
-
Keine
deprecated
-Methoden aufrufen -
Im Interface:
abstract
- return-Anweisungen
-
Attribute
- Öffentliche Konstanten dokumentieren
-
Im Interface:
final static
-
Anweisungen
-
Zeiger
this
,super
-
switch:
case
ist Block; Fortsetzung im nächsten case-Block dokumentieren -
if-else: jedes
else [if]
in neue Zeile -
Kurzformoperator
...?...:...
nicht verwenden
-
Zeiger
Changelog
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. |