Liebe Entwicklerkollegen,
Super! Ich bin begeistert!
Man könnte sogar so weit gehen zu sagen
Die Zeichenkodierung ist generell UTF8, Zeilenumbrüche werden im Unix-Format kodiert, Einrückungen erfolgen mit 4 Leerzeichen pro Einrückungsebene. Das Leerzeichen (U+0020) ist das einzige erlaubte weiße Zeichen in den Quelldateien. Jede Datei ist mit einem
Zeilenumbruch abzuschließen.
Das bedeutet, dass andere weiße Zeichen in Strings immer escaped sein müssen. Ich wüsste gerade nicht, dass bislang solche irgendwo vorkommen, aber wenn man die Coding Guidelines schonmal anfasst.
Ein Punkt, der noch nicht erwähnt wurde, ist die Zeilenlänge. Ich würde 120 Zeichen vorschlagen, (für Javadoc-Kommentare 80). Das wird von GitHub noch vernünftig dargestellt, und gibt genügend Platz für sprechende
Variablen- und Funktionsnamen. Zu kurze Zeilen führen sonst zu Umbrüchen, die die Lesbarkeit von Quellcode meines Erachtens eher verschlechtern. Für Javadoc wie gesagt kürzer, da sich bei langen Textzeilen sonst der menschliche Leser schwer tut, den Anfang
der nächsten Zeile zu finden.
Einen Code-Formatter mitzuliefern finde ich eine gute Idee. Bin mal gespannt, wie das praktisch funktioniert.
Bei der Reformatierung des Codes könnten „leere“ Einträge aus Kommentaren, die lediglich Variablennamen oder Throws-Listen wiederholen, gelöscht werden, z.B.
/**
* DMS-Export
an eine gewünschte Stelle
*
* @param myProzess
* @param inZielVerzeichnis
* @throws InterruptedException
*
@throws IOException
*
@throws WriteException
*
@throws PreferencesException
*
@throws DAOException
*
@throws SwapException
*
@throws TypeNotAllowedForParentException
*/
public
boolean startExport(Prozess
myProzess, String
inZielVerzeichnis)
throws IOException, InterruptedException,
WriteException,
PreferencesException, SwapException, DAOException,
TypeNotAllowedForParentException
oder
/**
*
@param autogenerated
the autogenerated to set
*/
public
void setAutogenerated(boolean
autogenerated) {
this.autogenerated
= autogenerated;
}
/**
* @return the
autogenerated
*/
public
boolean getAutogenerated() {
return
this.autogenerated;
}
Grüße
Matthias Ronge
|
Matthias Ronge
|
||||
|
|
|
|
|
|
Zeutschel GmbH
| Heerweg 2 | 72070 Tübingen | Deutschland
p: +49 (7071) 9706-62 | m: | f: +49 (7071) 9706-44 e: Matthias.Ronge@zeutschel.de | w: http://www.zeutschel.de |
|
|||
| Geschäftsführer/President: Joerg Vogler | Registergericht Stuttgart: HRB 380917 | ||||
From: kitodo-developer-bounces@kitodo.org [mailto:kitodo-developer-bounces@kitodo.org]
On Behalf Of Huber, Kathrin
Sent: Tuesday, November 22, 2016 2:55 PM
To: kitodo dev (kitodo-developer@kitodo.org)
Subject: [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@slub-dresden.de
www.slub-dresden.de | www.kitodo.org/