Coding Guidelines - Versionsgeschichte

Ullrich: /* Allgemeines */

2023-09-22T18:47:20Z

Allgemeines

← Nächstältere Version		Version vom 22. September 2023, 18:47 Uhr
Zeile 63:		Zeile 63:
	Verwechslungsgefahr besteht, wird die Menge der verwendbaren Zeichen eingeschränkt.		Verwechslungsgefahr besteht, wird die Menge der verwendbaren Zeichen eingeschränkt.
	Als Beispiel möge die folgende Methode dienen:		Als Beispiel möge die folgende Methode dienen:
	{{java\|~~coe~~ =		{{java\|code =
	void method() {		void method() {
	var хорошо = 15;		var хорошо = 15;

Ullrich: /* Allgemeines */

2023-09-22T18:42:01Z

Allgemeines

← Nächstältere Version		Version vom 22. September 2023, 18:42 Uhr
Zeile 59:		Zeile 59:
	und führen bei Mißachtung zu besonders unangenehmen Mißverständnissen.		und führen bei Mißachtung zu besonders unangenehmen Mißverständnissen.
	==Allgemeines==		==Allgemeines==
	Die Java-Spezifikation erlaubt ~~nahezu beliebige Folgen von~~ Unicode-~~Zeichen~~.		Die Java-Spezifikation erlaubt die Verwendung aller Unicode-Buchstaben.
	Da Java-Source-Dateien keine Encoding-Informationen enthalten und bei vielen Zeichen-Kombinationen		Da Java-Source-Dateien aber keine Encoding-Informationen enthalten und bei vielen Zeichen-Kombinationen
	Verwechslungsgefahr besteht, wird die Menge der verwendbaren Zeichen eingeschränkt		Verwechslungsgefahr besteht, wird die Menge der verwendbaren Zeichen eingeschränkt.
	* Es werden nur lateinischen Buchstaben a-z, A-Z und die Ziffern 0-9 verwendet.		Als Beispiel möge die folgende Methode dienen:
			{{java\|coe =
			void method() {
			var хорошо = 15;
			System.out.println("Wert ist " + хорошо);
			System.out.println("Wert ist " + хoрошо);
			}
			}}
			Kopiert man diesen Code in irgendeine Java-Klasse, giebt es in der letzten println-Zeile einen Compiler-Fehler.
			Das geschieht, weil das erste kleine "o" im Variablennamen kein russisches, sondern ein lateinisches "o" ist...

			* Es werden nur die lateinischen Buchstaben a-z, A-Z und die Ziffern 0-9 verwendet.
	* Umlaute und andere spezielle Buchstaben sind nicht erlaubt.		* Umlaute und andere spezielle Buchstaben sind nicht erlaubt.
	* Der Unterstrich "_" wird nur für Konstanten verwendet.		* Der Unterstrich "_" wird nur für Konstanten verwendet.
	* Das Dollar-Zeichen "$" bleibt der internen Verwendung durch anonyme inner classes vorbehalten und wird nicht verwendet.		* Das Dollar-Zeichen "$" bleibt der internen Verwendung durch anonyme inner classes vorbehalten und wird nicht verwendet.
	* Die Verwendung von Zahlen sollte vermieden werden, wenn Verwechlungsgefahr besteht, also zum Beispiel zwischen "eins" und "klein-Ell" oder zwischen "null" und "Oh.
	Für die Groß- und Kleinschreibungen gelten spezielle Regeln, es dürfen aber nie zwei Großbuchstaben hintereinander stehen		Für die Groß- und Kleinschreibungen gelten spezielle Regeln, es dürfen aber nie zwei Großbuchstaben hintereinander stehen
	(die einzige Ausnahme stellen die Konstanten dar), das gilt insbesondere für Abkürzungen.		(die einzige Ausnahme stellen die Konstanten dar), das gilt insbesondere für Abkürzungen.

Ullrich: /* Allgemeines */

2023-09-21T19:24:30Z

Allgemeines

← Nächstältere Version		Version vom 21. September 2023, 19:24 Uhr
Zeile 79:		Zeile 79:
	Einzelne Buchstaben sind für Typ-Parameter vorgeschrieben. Bei Variablen sind sie grundsätzlich zu vermeiden. Für		Einzelne Buchstaben sind für Typ-Parameter vorgeschrieben. Bei Variablen sind sie grundsätzlich zu vermeiden. Für
	for-Schleifen-Zähler sind sie erlaubt und ggf. auch als Parameter für sehr allgemeine bzw. sehr kurze Methoden.		for-Schleifen-Zähler sind sie erlaubt und ggf. auch als Parameter für sehr allgemeine bzw. sehr kurze Methoden.
			Reservierte Worte wie void oder int können -- per Definition -- nicht als Namen verwendet werden, da beschwert sich
			schon der Compiler. Darüber hinaus sind einige spezielle Worte zu vermeiden die zwar nicht reserviert sind, aber eine
			ganz spezielle Bedutung haben. Es sind dies
			* var
			* record

	==Packages==		==Packages==
	Package-Namen enthalten ausschließlich kleine Buchstaben, die durch Punkte getrennt werden.		Package-Namen enthalten ausschließlich kleine Buchstaben, die durch Punkte getrennt werden.

Ullrich: /* Methoden */

2023-09-21T19:19:38Z

Methoden

Ullrich: /* Deprectated-Tag */

2023-09-21T16:47:33Z

Deprectated-Tag

← Nächstältere Version		Version vom 21. September 2023, 16:47 Uhr
Zeile 256:		Zeile 256:

	=== Deprectated-Tag ===		=== Deprectated-Tag ===
	Ist eine Methode (Klasse, Feld, etc) mit {{java @Deprecated}} annotiert, geht dem ein – mit <code>@deprecated</code> versehener –		Ist eine Methode (Klasse, Feld, etc) mit {{java\|@Deprecated}} annotiert, geht dem ein – mit <code>@deprecated</code> versehener –
	JavaDoc-Kommentar voraus, der beschreibt was anstelle der Methode zu verwenden ist.		JavaDoc-Kommentar voraus, der beschreibt was anstelle der Methode zu verwenden ist.
	{{java\|code=		{{java\|code=

Ullrich: /* Deprectated-Tag */

2023-09-21T16:47:10Z

Deprectated-Tag

← Nächstältere Version		Version vom 21. September 2023, 16:47 Uhr
Zeile 255:		Zeile 255:
	wenn diese keine ungewöhnliche Logik enthalten, die dokumentiert werden sollte.		wenn diese keine ungewöhnliche Logik enthalten, die dokumentiert werden sollte.

	===Deprectated-Tag===		=== Deprectated-Tag ===
	Ist eine Methode (Klasse, Feld, etc) mit @Deprecated annotiert, geht dem ein – mit <code>@deprecated</code> versehener –		Ist eine Methode (Klasse, Feld, etc) mit {{java @Deprecated}} annotiert, geht dem ein – mit <code>@deprecated</code> versehener –
	JavaDoc-Kommentar voraus, der beschreibt was anstelle der Methode zu verwenden ist.		JavaDoc-Kommentar voraus, der beschreibt was anstelle der Methode zu verwenden ist.
			{{java\|code=
	/**		/**
	* Konvertiert {@link LocalDate} nach {@link String} mit deutschem Format (dd.MM.yyyy).		* Konvertiert {@link LocalDate} nach {@link String} mit deutschem Format (dd.MM.yyyy).
Zeile 272:		Zeile 273:
	return datum.format(DateTimeFormatter.ofPattern("dd.MM.yyyy"));		return datum.format(DateTimeFormatter.ofPattern("dd.MM.yyyy"));
	}		}
			}}

	===Leere Code-Blöcke===		===Leere Code-Blöcke===

Ullrich: Die Seite wurde neu angelegt: „Category:IT Category:Java =Formatierung= Die Formatierung umfaßt die Verwendung von Leerzeichen, Leerzeilen, Zeilenumbrüchen und Einrückungen. Eine…“

2023-09-21T16:36:49Z

Die Seite wurde neu angelegt: „Category:IT Category:Java =Formatierung= Die Formatierung umfaßt die Verwendung von Leerzeichen, Leerzeilen, Zeilenumbrüchen und Einrückungen. Eine…“

Neue Seite

[[Category:IT]]
[[Category:Java]]
=Formatierung=
Die Formatierung umfaßt die Verwendung von Leerzeichen, Leerzeilen, Zeilenumbrüchen und Einrückungen.
Eine einheitliche Formatierung trägt wesentlich dazu bei, daß Code schnell gelesen werden kann.
Zudem werden Kollisionen beim Einchecken in das Code-Repository vermieden die dadurch entstehen, daß
Entwickler den Code unterschiedlich formatieren.
Die Frage welche Formatierung die Richtige ist, läßt sich nicht beantworten. Der eine Entwickler bevorzugt das eine,
der nächste Entwickler findet was anderes besser. Die Regeln bemühen sich, einen Kompromiß zwischen Kompaktheit und Lesbarkeit
zu finden.

Die Formatierung sollte wird über einen Eclipse-Formatter gesteuert werden, der über den Workspace Mechanic
konfiguriert wird. Die Ausführung des Formatters wird – ebenfalls durch den Workspace Mechanic – als "SaveAction" in Eclipse eingestellt, so daß bei der Code jedem Speichern formatiert wird. Darüber hinaus sorgt der
Formatter dafür, daß einzelne Statements in Schleifen und anderen Kontroll-Strukturen in geschweifte Klammern
gesetzt werden und überflüssige Leerzeichen am Zeilenende entfernt werden.

Was für die eine eine willkommene Erleichterung darstellt, empfinden andere als Gängelung. Die Formatierung
sollte zwar nicht ganz ausgehebelt werden, kann aber – wie weiter unten beschrieben – durch zusätzliche
Zeilenumbrüche aufgelockert werden. Wie eingangs betont, sollen Codier-Regeln helfen und nicht behindern, in
diesem Sinne sollte der Formatter denn auch als automatische Unterstützung wahrgenommen werden.
==Leerzeilen==
Der Formatter komprimiert aufeinanderfolgende Leerzeilen, so daß immer nur eine Leerzeile stehen bleibt.
Einzelne Leerzeilen werden jedoch nicht entfernt. Der Entwickler kann somit steuern, ob er zum Beispiel zwischen
zwei Feld-Definitionen einer Klasse eine Leerzeile lassen möchte oder nicht.

An bestimmten Stellen – zum Beispiel zwischen package- und import-Deklaration – erzwingt der Formatter
Leerzeilen, die nicht gelöscht werden können.
==Zeilenumbrüche==
Der Zeilenumbruch wird vom Formatter automatisch ausgeführt. Das sieht bisweilen nicht so übersichtlich aus, wie
man sich das wünscht, zum Beispiel bei langen Parameter-Listen oder bei Methoden-Verkettung. Der Entwickler
kann dann zur Erhöhung der Lesbarkeit den Umbruch mit Zeilenkommentaren erzwingen:
private Stream<DtoProdukt> produktStream(DtoPersonendaten person) {
return Optional.of(person).map(DtoPersonendaten::getProduktListe).orElse(Collections.emptyList()).stream();
}
Durch Zeilenend-Kommentare wird jeder Methoden-Aufruf in eine eigene Zeile gestellt:
private Stream<DtoProdukt> produktStream(DtoPersonendaten person) {
return Optional.of(person) //
.map(DtoPersonendaten::getProduktListe) //
.orElse(Collections.emptyList()) //
.stream();
}
Die Einrückung unterhalb der "return"-Zeile wird vom Formatter automatisch hinzugefügt.
Das ist auch der empfohlene Stil für Methoden-Verkettung, wie sie etwa für Object-Builder typisch ist: Jedes
Statement in einer neuen Zeile.
=Namenskonventionen=
Die Java-Spezifikation macht nur wenig Einschränkungen, was die Wahl von Bezeichnern angeht. Grundsätzlich
kann jeder Bezeichner – was auch immer er bezeichnet – aus einer nahezu beliebigen Folge von Unicode-Zeichen
bestehen. Läßt man dieser Freiheit tatsächlich alle Zügel schießen, handelt man sich eine ganze Menge Probleme
ein. Angefangen von der Verwechslungsgefahr und den unvermeidlichen Encoding-Problemen, bis zu der Frage ob
der Bezeichner nun eine Klasse eine Variable oder einen generischen Typ bezeichnet. Namenskonventionen helfen,
den Code auch ohne IDE-Unterstützung jederzeit flüssig lesen zu können.

Die Konventionen haben zwei Aspekte: Zum einen gibt es rein syntaktische Regeln, die üblicherweise mit regulären
Ausdrücken beschrieben und von Sonar-Regeln überprüft werden können. Dazu gehört etwa die Regel, daß jede
Methode mit einem kleinen Buchstaben beginnen soll. Diese Regeln sind leicht zu merken und zu befolgen.
Zum anderen gibt es Regeln, die sich auf den Zweck des Bezeichneten beziehen und Informationen in den Code
hineintragen. Dazu gehört die Regel, daß Klassen mit Substantiven bezeichnet werden sollen. Diese Regeln
erfordern Kreativität vonseiten des Entwicklers. Sie können nicht mit mechanischen Regeln kontrolliert werden
und führen bei Mißachtung zu besonders unangenehmen Mißverständnissen.
==Allgemeines==
Die Java-Spezifikation erlaubt nahezu beliebige Folgen von Unicode-Zeichen.
Da Java-Source-Dateien keine Encoding-Informationen enthalten und bei vielen Zeichen-Kombinationen
Verwechslungsgefahr besteht, wird die Menge der verwendbaren Zeichen eingeschränkt
* Es werden nur lateinischen Buchstaben a-z, A-Z und die Ziffern 0-9 verwendet.
* Umlaute und andere spezielle Buchstaben sind nicht erlaubt.
* Der Unterstrich "_" wird nur für Konstanten verwendet.
* Das Dollar-Zeichen "$" bleibt der internen Verwendung durch anonyme inner classes vorbehalten und wird nicht verwendet.
* Die Verwendung von Zahlen sollte vermieden werden, wenn Verwechlungsgefahr besteht, also zum Beispiel zwischen "eins" und "klein-Ell" oder zwischen "null" und "Oh.
Für die Groß- und Kleinschreibungen gelten spezielle Regeln, es dürfen aber nie zwei Großbuchstaben hintereinander stehen
(die einzige Ausnahme stellen die Konstanten dar), das gilt insbesondere für Abkürzungen.
korrekt sind
HtmlRenderer renderHtmlPage ausgewaehlterKunde markTransactionForRollback
falsch sind
HTMLRenderer renderHTMLpage ausgewählterKunde
Generell soll jeder Bezeichner möglichst genau beschreiben, was das bezeichnete darstellt (Klassen, Interfaces),
enthält (Konstanten, Variablen, Felder) oder tut (Methoden). Abkürzungen sollten grundsätzlich vermieden werden,
bei fachliche getriebenen Abkürzungen sollte immer zwischen Nutzen und Klarheit abgewogen werden. Vor allem
dürfen keine Mißverständnisse durch die Verwendung entstehen.
Einzelne Buchstaben sind für Typ-Parameter vorgeschrieben. Bei Variablen sind sie grundsätzlich zu vermeiden. Für
for-Schleifen-Zähler sind sie erlaubt und ggf. auch als Parameter für sehr allgemeine bzw. sehr kurze Methoden.
==Packages==
Package-Namen enthalten ausschließlich kleine Buchstaben, die durch Punkte getrennt werden.
de.snakeoil.common.util.mock

==Klassen==
Klassen-Namen bestehen aus einer Folge von Worten, die eine substantivische Konstruktion bilden. Jedes neue
Wort beginnt mit einem Großbuchstaben, alle anderen Buchstaben sind klein. Das gilt insbesondere für
Abkürzungen: Html statt HTML. "Substantivische Konstruktion" bedeutet, daß der Klassen-Name als ganzes
genommen einen Gegenstand, eine Idee oder ein Konzept bezeichnet, also z.B. einen "Kunden", einen "Builder",
einen "Controller" oder ein "Entity". Durch zusätzliche Worte – und das müssen keine Substantive sein – kann die
Natur der Klasse genauer spezifiziert werden. Zum Beispiel "PathBasedKeycloakConfigResolver".

Klassen-Namen beginnen immer mit einem Großbuchstaben richtig sind
FooErgebnisMapper HtmlRenderer CustomerFactoryBuilder
falsch ist
FOOErgebnisMapper htmlRenderer Customerfactorybuilder
Der Name einer Klasse, die eine Unterkasse von Exception erweitert – also eine Exception definiert – endet immer mit "Exception".

Der Name einer abstrakten Klasse (eine Klasse deren Deklaration der modifier "abstract" vorangestellt ist) beginnt immer mit "Abstract".
==Interfaces==
Interfaces werden nach den gleichen Regeln wie Klassen benannt.
Bezeichnet das Interface eine Eigenschaft die ein Klasse haben kann, darf es auch mit einem englischen Adjektiv oder Adverb
bezeichnet werden. Beispiele dafür sind z.B. die JDK-Interfaces Runnable und Closeable. Der Name beginnt in
jedem Falle mit einem Großbuchstaben.

Es ist allgemein nicht mehr üblich, einem Interface-Bezeichner ein großes "I" voranzustellen. da man im Code
normalerweise mit den Interfaces arbeitet und nicht mit den implementierenden Klassen, sollte das Interface den
allgemeineren Namen tragen und die implementierenden Klassen den spezielleren.
:Interface: PasswordService
:Implementierung: PasswordServiceLdap
:Implementierung: PasswordServiceDummy
oder – wenn nur eine einzige Implementierung existiert:
:Interface: DataReaderAdapter
:Implementierung: DataAdapterReaderImpl
Das Suffix "Impl" ist immer dann sinnvoll, wenn nur eine einzige Implementierung existiert, die Verwendung eines
Interfaces jedoch zwingend erforderlich ist. Die Endung "Default" kann sinnvoll sein, wenn mehrere
Implementierungen möglich oder vorgesehen sind, zunächst aber nur eine Implementierung erstellt wird.

==Methoden==
Methoden-Namen bestehen aus einer Folge von Worten, die eine verbiale Konstruktion bilden. Jedes neue Wort
beginnt mit einem Großbuchstaben, alle anderen Buchstaben sind klein. Das gilt insbesondere für Abkürzungen:
Html statt HTML. "verbiale Konstruktion" bedeutet, daß der Methoden-Name als Ganzes genommen eine Tätigkeit
bezeichnet.

Methoden-Namen beginnen immer mit einem Kleinbuchstaben. z.B.
copyAddresse() run() renderHtmlPage()
Liefert die Methode einen Boolean-Wert, sollte der Name einer Aussage entsprechen, die wahr oder falsch sein kann:
enthaeltGueltigeAdresse() isEmpty()
Getter und Setter (definition) gehören weiterhin zum Standard-Repertoire der Java-Programmierung. Je nach
Kontext kann der Zugriff auf eine Objekt-Eigenschaft, aber auch durch Methoden gestaltet werden die nicht der
get-/set-Konvention entsprechen. Eine genaue Beschreibung steht noch aus, es ist jedoch bei der Wahl von
Methoden-Namen immer darauf zu achten, daß keine Mehrdeutigkeiten entstehen. das gilt besonders für
englischsprachigen Bezeichnungen, da Substantive und Verben im Englischen nicht immer zu unterscheiden sind:
Bezeichnet challenge(), daß die Methode eine Challenge liefert oder eine "Herausforderung" ausführt?

==Variablen==
Gemeint sind damit lokale Variablen, formale Methoden-Parameter und nicht-statischen Instanz-Variablen.
Variablen-Namen bestehen aus einer Folge von Worten, die eine substantivische Konstruktion bilden. Jedes neue
Wort beginnt mit einem Großbuchstaben, alle anderen Buchstaben sind klein.

Variablen-Namen beginnen immer mit einem Kleinbuchstaben.

Variablen enthalten Instanzen von Klassen und bezeichnen damit üblicherweise "Dinge" oder Instanzen von Ideen
oder Konzepten. Dementsprechend werden sie ähnlich wie Klassen bezeichnet z.B.
requestHeader person gesuchte

https://docs.oracle.com/javase/tutorial/java/generics/types.html

Da – vor allem lokale – Variablen meist Dinge enthalten, die zu einem bestimmten Zweck gebraucht werden, sollte
man sie dem Zweck entsprechend attributieren. Also besser "gesuchtePerson" statt "person" oder gar "p".

==Konstanten==
Konstanten sind in Java statische Felder in Klassen oder Interfaces.
Konstanten-Namen beginnen mit einem großen Buchstaben enthalten nur große Buchstaben, Ziffern und das Unterstrich-Zeichen.
Da nur große Buchstaben verwendet werden, dient der Unterstrich als Wort-Trenner z.B.
STEUERSATZ WARTE_ZEIT_NACH_ABLAUF_IN_TAGEN

==enums==
Java-Enums sind Klassen. Für den Namen der enum-Klasse gelten daher die gleichen Regeln wie für jeden Klassennamen.
Für die Namen der enum-Instanzen gelten die Regeln für Konstanten-Namen – nur Großbuchstaben, getrennt
durch Unterstrich.
==Typ-Parameter==
Typ-Parameter werden bei der Definition generischer Klassen und Methoden verwendet. Den von Oracle
stammenden Regeln folgend werden Typ-Parameter durch einzelne, große Buchstaben bezeichnet. Hintergrund
für diese spartanische Namensgebung ist, daß in der Regel nur wenige Typ-Parameter benötigt werden und diese
sofort als solche erkennbar sein sollen und die Gefahr der Verwechslung mit anderen Bezeichnern möglichst gering gehalten werden sollte z.B.
public interface List<E> extends Collection<E>
Oracle empfiehlt, folgende Buchstaben zu verwenden:
{| class="wikitable"
|+
| Zweck || typische Verwendung
|-
|E || Element JDK-Collection-Klassen wie "List" verwenden das E
|-
|K || Key Schlüssel, wie im Map-Interface
|-
|N || Number
|-
|T, R || Type allgemeiner Typ, wie im funktionalen Interface "Function"
|-
|V || Value Wert, wie im "Map"-Interface
|-
|S, U, V || Type Wenn T und R nicht genug sind.
|}
Es ist empfehlenswert, für Typ-Parameter immer auch einen JavaDoc-Kommentar zu schreiben. Dazu wird das @param-Tag verwendet:
/**
* @param <E> the type of elements in this list
**/
public interface List<E> extends Collection<E>
==Klassen-Aufbau==
Um die Komponenten der Klasse schnell wiederzufinden, sollen sie immer in der gleichen Reihenfolge aufgeführt werden:
#Package-Deklaration
#Import-Statements
#Klassen- oder Interface-Deklaration
#Klassen-Variablen (statische Felder)
#Instanz-Variablen
#Konstruktoren
#Methoden
Die Reihenfolge der import-Deklarationen wird durch die Eclipse-Funktion "organize imports" sichergestellt.
Innere Klassen folgen dem gleichen Aufbau und werden deklariert bevor sie das erste Mal verwendet werden
Variablen werden nach Sichtbarkeit sortiert: public – protected – private.
Für "package visible" Variablen gibt es keine Vorgabe, sie können nach dem "public"- oder derm "protected"-Block stehen.
Die Methoden werden nicht nach Sichtbarkeit, sondern nach funktionaler Zusammengehörigkeit gruppiert.
private Methoden werden üblicherweise nach der Methode aufgeführt, die sie als erste aufruft.

=Kommentare=
Das Erzwingen von Kommentaren – z.B. über Sonar-Regeln – führt in der Regel dazu, daß der Code
große Mengen von Kommentaren enthält, die zwar formal korrekt, inhaltlich aber völlig nutzlos sind.
Der völlige Verzicht auf Kommentare andererseits funktioniert nur dann, wenn sich der Codierer – insbesondere was
die Wahl der Bezeichner anbelangt – besonders gewissenhaft um die Code-Qualität bemüht.
Die folgenden Richtlinien versuchen einen Kompromiß zu finden, der einerseits den Entwickler nicht überfordert
und andererseits die Kommentar-Qualität erhöht.
Wie auch immer kommentiert wird, es gilt der eherne Grundsatz
:<q>Kommentar und Implementierung müssen immer miteinander in Einklang stehen</q>
==Allgemeines==
Den JavaDoc-Standard zu forcieren ist nur dann sinnvoll, wenn die API-Dokumentation zur Anwendung generiert
und verwendet wird. In der Praxis führt das nur zu einem "Rauschen" durch inhaltsfreie Kommentar-Skelette.
Es ist aber sinnvoll, JavaDoc als Grundlage zu verwenden, Kommentare folgen daher der Struktur nach den JavaDoc-Konventionen.
Das gilt insbesondere für Klassen- und Methoden-Kommentare:
* Der Kommentar beginnt mit <code>/**</code> und endet mit <code>**/</code>, jede Zeile beginnt mit <code>*</code>
* Die erste Zeile endet mit einem Punkt, gefolgt von einem <p>-Tag
* Die Formulierung erfolgt immer in der dritten Person:
: "Liefert den Wert..." und nicht "Liefere den Wert..."
* Die Formatierung übernimmt der Formatter
JavaDoc-Kommentar-Skelette können in Eclipse schnell erzeugt werden durch Eingabe von "/**" und "Return"-
Taste über dem zu kommentierenden Element.
Diese Skelette müssen entweder ausgefüllt oder gelöscht werden. Sie dürfen nicht unverändert stehengelassen werden.

==Muß==
Das Minimum an Kommentaren, das gefordert wird.
===Copyright-Vermerk===
Am Anfang jeder Klassen-Datei steht – vor der package-Deklaration – der Kommentar mit dem Copyright-Vermerk
und dem Jahr der Erstellung der Klasse
/*
* Copyright (c) Swinging Pig Inc. 2019
*/
===Klassen===
Unmittelbar vor der Klassen-Deklaration steht der Klassen-Kommentar.
in einer Zeile wird beschrieben, was die Klasse tut.
/**
* Lädt über den gegebenen {@link RealmClient} die Konfiguration aus den Excel-Sheets.
*/
public class KonfigurationExcelFileLoader extends AbstractExcelFileLoader {
===public und protected Methoden===
Die public und protected Methoden bilden das Interface der Klasse. Jede Schnittstellen-Methode hat einen Kommentar.
In einer Zeile wird beschrieben, was die Methode tut.
/**
* Liefert den Wert des ersten Attributs vom angegebenen Typ in der Liste.
*/
public Optional<String> firstAttributValue(CustomerAttribute attributTyp) {
Ausgenommen von der Regel sind
* Getter
* Setter
* Konstruktoren
wenn diese keine ungewöhnliche Logik enthalten, die dokumentiert werden sollte.

===Deprectated-Tag===
Ist eine Methode (Klasse, Feld, etc) mit @Deprecated annotiert, geht dem ein – mit <code>@deprecated</code> versehener –
JavaDoc-Kommentar voraus, der beschreibt was anstelle der Methode zu verwenden ist.
/**
* Konvertiert {@link LocalDate} nach {@link String} mit deutschem Format (dd.MM.yyyy).
* <p>
* NB: Im Unterschied zu {@link #asGermanDate(LocalDate)} fliegen hier exceptions.
*
* @param datum
* zu konvertierendes {@code LocalDate}-Objekt
* @return String mit Format dd.MM.yyyy
* @deprecated use asGermanDate() instead
*/
@Deprecated
public static String toLocalString(LocalDate datum) {
return datum.format(DateTimeFormatter.ofPattern("dd.MM.yyyy"));
}

===Leere Code-Blöcke===
Jeder leere Code-Block enthält einen Kommentar, der angibt, warum der Block vorhanden ist.
private Convert() {
// Instantiierung verhindern
}
Ausgenommen davon sind leere Lambda-Ausdrücke (dafür wird aber in der Regel besser eine Konstante definiert).
==Kann==
Bei Bedarf können Kommentare hinzugefügt werden, die über das obige Minimum hinausgehen.
Wenn eine geänderte Implementierung den Kommentar überflüssig macht, ist das immer vorzuziehen.
===Klassen===
Neben der Beschreibungs-Zeile, können im Klassen-Kommentar Details beschrieben werden, die zur Klasse gehört.
* Gebrauch der Klasse, Verwendung der Methoden (z.B. wann welche zu verwenden ist)
* fachliche Motivation
* Merkwürdigkeiten, ungewöhnliche Dinge in der Klasse
Was sich auf eine Methode bezieht, gehört in den Methoden-Kommentar.
===Methoden===
Neben der Beschreibungs-Zeile, können im Methoden-Kommentar Details beschrieben werden, die zur Methode gehören.
* Parameter
* fachliche Motivation
* Merkwürdigkeiten, ungewöhnliches in der Implementierung
Parameter werden nach JavaDoc-Standard mit den entsprechenden Annotationen dokumentiert.
Es gilt: entweder alle Parameter (und ggf. das Ergebnis) kommentierten, oder gar keinen.
Unvollständige Dokumentation ist zu vermeiden.
/**
* Bestimmt aus dem Code die Authentication-Session und daraus die redirect-URL.
*
* @param session
* Keycloak-Session
* @param code
* der zu untersuchende Code
* @return die redirect-URL aus der auth-Session zu der der code gehört oder {@code null}
*/
public static String getOriginalRedirectUriFromCode(KeycloakSession session, String code) {
===private Methoden===
private-Methoden können bei bedarf genauso kommentiert werden wie public- und private-Methoden, erforderlich
ist das aber nicht.
===Konstanten===
Konstanten sollten durch den Namen ausreichend beschrieben sein. Ist nähere Erläuterung erforderlich,
kann das "formlos" in einer Zeile darüber geschehen:
// UTC-Zone für die Konvertierung zonenloser Zeiten
private static final ZoneId ZONE_UTC = ZoneId.of("UCT");
Da in der Regel kein JavaDoc generiert wird, ist kein 3-zeiliger JavaDoc-Kommentar erforderlich; verboten ist das
aber nicht.
==Verboten==
Kommentare sollen dem Code nur Informationen hinzufügen, die dem Code nicht inherent sind.
was mit sprechenden Namen ausgedrückt werden kann (und auch ausgedrückt wird), wird nicht kommentiert.
* Fehlerhafte Kommentare
* Kommentare zu nicht existierenden Parametern
* Kopierte Kommentare
* ...
* redundante Kommentare
* Kommentare, die Methoden-Namen in Prosa wiederholen
* Sätze wie "Standard-Konstruktor"
* getXyz() → "Setzt das xyz-Feld"
* auskommentierter Code (vor Übergang in die STU löschen)
* @param und @result Tags ohne erklärenden Kommentar
* Trennungs-Konstrukte (z.B. // -------------------)
:Das "Clean Code"-Buch verbietet solche Konstrukte, weil die Klasse ja offensichtlich zu groß ist.
:Das muß aber IMHO nicht zu strikt gehandhabt werden
* Das gleiche gilt für Kommentare, die nicht zu einer Methode oder einem Feld gehören.
:Das macht man gelegentlich, um Methoden-Gruppen zu kommentieren

← Nächstältere Version		Version vom 21. September 2023, 19:19 Uhr
Zeile 117:		Zeile 117:
	Implementierungen möglich oder vorgesehen sind, zunächst aber nur eine Implementierung erstellt wird.		Implementierungen möglich oder vorgesehen sind, zunächst aber nur eine Implementierung erstellt wird.

	==Methoden==		== Methoden ==
	Methoden-Namen bestehen aus einer Folge von Worten, die eine verbiale Konstruktion bilden. Jedes neue Wort		Methoden-Namen bestehen aus einer Folge von Worten, die eine verbiale Konstruktion bilden. Jedes neue Wort
	beginnt mit einem Großbuchstaben, alle anderen Buchstaben sind klein. Das gilt insbesondere für Abkürzungen:		beginnt mit einem Großbuchstaben, alle anderen Buchstaben sind klein. Das gilt insbesondere für Abkürzungen:
Zeile 127:		Zeile 127:
	Liefert die Methode einen Boolean-Wert, sollte der Name einer Aussage entsprechen, die wahr oder falsch sein kann:		Liefert die Methode einen Boolean-Wert, sollte der Name einer Aussage entsprechen, die wahr oder falsch sein kann:
	enthaeltGueltigeAdresse() isEmpty()		enthaeltGueltigeAdresse() isEmpty()
	Getter und Setter ~~(definition)~~ gehören weiterhin zum Standard-Repertoire der Java-Programmierung. Je nach		Getter und Setter gehören weiterhin zum Standard-Repertoire der Java-Programmierung. Je nach
	Kontext kann der Zugriff auf eine Objekt-Eigenschaft, aber auch durch Methoden gestaltet werden die nicht der		Kontext kann der Zugriff auf eine Objekt-Eigenschaft, aber auch durch Methoden gestaltet werden die nicht der
	get-/set-Konvention entsprechen. Eine genaue Beschreibung steht noch aus, es ist jedoch bei der Wahl von		get-/set-Konvention entsprechen. Eine genaue Beschreibung steht noch aus, es ist jedoch bei der Wahl von
	Methoden-Namen immer darauf zu achten, daß keine Mehrdeutigkeiten entstehen. das gilt besonders für		Methoden-Namen immer darauf zu achten, daß keine Mehrdeutigkeiten entstehen. das gilt besonders für
	~~englischsprachigen~~ Bezeichnungen, da Substantive und Verben im Englischen nicht immer zu unterscheiden sind:		englischsprachige Bezeichnungen, da Substantive und Verben im Englischen nicht immer zu unterscheiden sind:
	Bezeichnet challenge(), daß die Methode eine Challenge liefert oder eine "Herausforderung" ausführt?		Bezeichnet challenge(), daß die Methode eine Challenge liefert oder eine "Herausforderung" ausführt?