Coding Guidelines - Kitodo-Developer - SLUB-Domäne

22 Nov 2016

Liebe Entwickler Kollegen,

zum Start in unser Refactoring möchten wir den bestehenden Code gern mittels eines
Formatters an die Coding Guidlines anpassen.
Wir haben dafür die Coding Guidlines noch einmal genauer unter die Lupe genommen und
möchten euch ein paar kleine Änderungen vorschlagen.
Wir hätten dazu gern ein Feedback von euch und würden bei einer mehrheitlichen Zustimmung
bereits mit aktualisierten Coding Guidlines arbeiten, in dem Vertrauen darauf, dass diese
daraufhin auch von der Mitgliederversammlung angenommen werden.

Hier unsere Änderungsvorschläge:

Die Zeile:
"Der Quellcode muss kompatibel zum Java6-Standard sein."

ändern in:
"Der Quellcode muss kompatibel zum Java7-Standard sein."

Erklärung:
Java 7 ist mittlerweile etabliert genug, dass es von den meisten Systemen unterstützt
wird. Wir möchten auch die Vorteile dieser Version nutzen.
-------------------------------
Hinzufügen des Absatzes:
"Der Quellcode muss mit dem mitgelieferten Codeformatter formatiert sein"

Erklärung:
Das Nutzen verschiedener Codeformatter führt in manchen Fällen zu einer Vielzahl von
Änderungen in der commit history. Im schlimmsten Fall werden Dateien commited, die keine
funktionalen Änderungen haben, aber vom Entwickler formatiert wurden und wegen
abweichender Zeilenumbrüche als Änderung eingehen.
Insbesondere das Reviewen von Code wird dadurch deutlich erschwert.
---------------------------------
Die Zeile:
"Exceptions (error) müssen immer aufgefangen und geeignet behandelt, mindestens aber
im Log registriert werden. Letzteres gilt auch für unkritische Programmfehler (warning)
und Hinweise (notice)."

ändern in:
"Exeptions (error) müssen immer geeignet behandelt werden und gegebenenfalls bis zu
der Stelle durchgereicht werden, an der dies möglich ist. Sie müssen immer im Log
registriert werden. Letzteres gilt auch für unkritische Programmfehler (warning) und
Hinweise (notice)."

Erklärung:
Errors sollten nur gefangen werden, wenn sie entsprechend behandelt werden können. An
jeder Stelle jeden beliebigen Fehler zu fangen führt im schlimmsten Fall dazu, dass
Methoden fehlerfrei durchlaufen, ohne aber das zu tun, was sie versprechen. Stattdessen
sollten Fehler an aufrufende Methoden kommuniziert werden, damit diese entsprechende
Schritte einleiten können (z.B. erneutes aufrufen, eventuell mit abweichenden Parametern,
oder Ausgabe im Frontend "fehlerhafte Eingabe")
---------------------------
Die Zeile:
"Jede Klasse, jede Methode und jede Klassenvariable ist im phpDoc- bzw. JavaDoc
-Standard zu dokumentieren. Zusätzlich sollte im Quellcode ausführlich von
Zeilenkommentaren zur Dokumentation Gebrauch gemacht werden."

ändern in:
"Jede Klasse, jede öffentliche Methode und jede Klassenvariable ist im phpDoc- bzw.
JavaDoc-Standard zu dokumentieren. Der Quellcode sollte durch sprechende Bezeichnungen und
kleine Methoden weitestgehend selbsterklärend sein. Zur Erläuterung von Funktionalität
sollte im Quellcode von Zeilenkommentaren Gebrauch gemacht werden."

Erklärung:
Die übermäßige Verwendung von Kommentaren führt erfahrungsgemäß leider dazu, dass
Quellcode geändert wird, die Kommentare aber nicht, so dass Kommentar und tatsächliche
Funktion voneinander abweichen. Im schlimmsten Fall ist dies nicht offensichtlich und ein
Fehlverhalten des Codes wird angenommen oder nicht bemerkt.
Es ist anzustreben, dass Javacode durch geeignete Variablen- und Methodennamen
weitestgehend selbsterklärend ist und auf Zeilenkommentare verzichtet werden kann.
--------------------------------------
Die Zeile:
"Die Zeichenkodierung ist generell UTF8, Zeilenumbrüche werden im Unix-Format
kodiert, Einrückungen erfolgen mit Tabs. Jede Datei ist mit einem Zeilenumbruch
abzuschließen."

ändern in:
"Die Zeichenkodierung ist generell UTF8, Zeilenumbrüche werden im Unix-Format
kodiert, Einrückungen erfolgen mit Leerzeichen (4 Leerzeichen pro Einrückung). Jede Datei
ist mit einem Zeilenumbruch abzuschließen."

Erklärung:
Der überwiegende Teil des Codes wird mit Spaces eingerückt. Nur neuere Codeteile sind mit
Tabs eingerückt, da die letzten Coding Guidelines dies vorschrieben.
Verschiedene Text Editoren oder IDE's können eine verschiedene Anzahl von Leerzeichen
pro Tab konfigurieren. Damit kann der Source Code unleserlich werden und ist vor allem
nicht einheitlich.
------------------------------------------
Die Zeile:
"Für Schleifen sollten Java5-Konstrukte für typsichere Listen benutzt werden."
ändern in:
"Für Schleifen sollten Konstrukte für typsichere Listen benutzt werden."
Erklärung:
Das diese Konstrukte für typsichere Listen mit Java-5 eingeführt wurden kann man als
Randnotiz stehen lassen, können aber in den Guidelines selber zur Verwirrung führen. Da
der Code Java-7 kompatibel werden soll, sollte es selbstverständlich sein, auch die bis
dato verfügbaren effizientesten Mittel und Wege, die Java-7 bietet zu nutzen.

Im Anhang findet ihr die angepassten Coding Guidelines, wie sie zur Abstimmung an die
Mitgliederversammlung gehen würden.

Liebe Grüße
Kathrin Huber

Kathrin Huber
Digitale Bibliothek
Sächsische Landesbibliothek -
Staats- und Universitätsbibliothek Dresden (SLUB)
Abteilung IT, Referat 2.1
01054 Dresden
Besucheradresse: Zellescher Weg 18, 01069 Dresden
Tel.: +49 351 4677 242 | Fax: +49 351 4677 711
E-Mail: kathrin.huber(a)slub-dresden.de
www.slub-dresden.de<http://www.slub-dresden.de/>
<mailto:jens.bemme@slub-dresden.de> | www.kitodo.org/