[KitodoDev] Coding Guidelines

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/