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/
Liebe Entwickler,
im Rahmen unseres Refactorings, werden wir viel Funktionalität in Maven Module auslagern.
Dafür haben wir nun Vorgaben erarbeitet, die für jede Modulentwicklung gelten.
Ihr findet diese im GitHub Wiki<https://github.com/kitodo/kitodo-production/wiki/Structure-of-modules>.
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/
Liebe Entwickler,
aufgrund des gestarteten DFG Projektes zur Weiterentwicklung von
Kitodo.Production und damit eingehend auch Neuanstellungen von
Entwicklern aber auch um neuen Community Entwicklern eine Handreichung
über die Entwicklung im Kitodo.Production Community Projekt zu geben,
habe ich einmal die wichtigsten Punkte zusammen gefasst und ins GitHub
basierende Wiki unter
https://github.com/kitodo/kitodo-production/wiki/Hinweise-f%C3%BCr-Entwickl…
gestellt. Fragen und Kommentare entweder über die Liste oder direkt an
mich. Die Bearbeitung direkt im GitHub Wiki ist auch möglich, jedoch
sollten fundamentale Änderungen bitte vorher abgesprochen werden.
Vielen Dank und viele Grüße
Henning Gerhardt
--
Henning Gerhardt
Sächsische Landesbibliothek -
Staats- und Universitätsbibliothek Dresden (SLUB)
Abt. Informationstechnologie (IT), Ref. Digitale Bibliothek
01054 Dresden
Besucheradresse: Zellescher Weg 18, 01069 Dresden
Tel.: +49 351 4677 227 | Fax: +49 351 4677 711
E-Mail: henning.gerhardt(a)slub-dresden.de
www.slub-dresden.de
Liebe Kitodo Entwickler,
für das bevorstehende Refactoring im Rahmen des DFG Projektes gibt es
noch eine Änderung, die die Basis dafür sein wird: Die Umstellung des
bisherigen Bauprozess von ant mit seiner beliebigen Struktur auf einen
Maven basierenden Bauprozess und der entsprechend typischen Struktur
eines Maven Projektes.
Die dafür notwendigen Anpassungen finden aktuell in einem
eigenständigen Branch [1] statt und werden nach Abschluss der Arbeiten
in den master Branch von Kitodo.Production integriert.
Viele Grüße
Henning Gerhardt
[1] https://github.com/Basti890/kitodo-production/tree/maven_structure
Liebe Kitodo Entwickler,
sicher wartet ihr schon gespannt auf das Ergebnis unserer Codeanalysen und die Entscheidung, wie es mit Kitodo weiter gehen soll.
Ich freue mich euch mitteilen zu können, dass wir zu einer Entscheidung kommen konnten.
Unter Berücksichtigung aller Vor- und Nachteile sind wir zu dem Schluss gekommen, dass ein Refactoring im Rahmen der innerhalb des Projekts zur Verfügung stehenden Ressourcen den größten Mehrwert bietet.
Wie sind wir dabei vorgegangen?
Nach mehreren Ansätzen aus verschiedenen Richtungen (Systemarchitektur erstellen, Technologieanalysen, Anforderungsanalyse...) haben wir entschieden, dass wir erst nach einem tatsächlichen Refactoring wirklich abschätzen können, welche Variante geeigneter ist.
Die Herausarbeitung ausgewählter Module aus dem bestehenden Code erwies sich als durchaus machbar. Manche Teile müssen so oder so neu gebaut werden, da erschien der Overhead einer Neuimplementierung unverhältnismäßig gegenüber der Herauslösung der Funktionalität in eigene Module. Die teilweise schlechte Codequalität lässt sich durch Refactoring beheben und beeinflusst nicht die Modularisierung.
Der Funktionsumfang von Kitodo muss von außen (nicht aus dem Code heraus) bestimmt werden. Wir gehen nun den Weg von einer vollumfänglichen Anwendung einzelne Funktionalitäten herauszuarbeiten und nicht gebrauchte Stücke zu entfernen. Die Gefahr Funktionalität unbewusst "auszubauen" (oder beim Neubau zu vergessen) besteht damit so oder so, ist im Falle eines Refactorings aber deutlich geringer.
Uns erschien die Tatsache einer sich entwickelnden Anwendung, die aber von Anfang an jegliche Funktionalität bietet, in Anbetracht der begrenzten Projektzeit, als sichererer Weg im Vergleich zu einem Neubau, der im schlimmsten Fall am Ende der zwei Jahre noch nicht den vollen Funktionsumfang besitzt.
Es wird nun in Zukunft, insbesondere in den nächsten Monaten, zu einigen grundlegenden Änderungen im Code kommen.
Wir werden euch über den Fortschritt auf dem Laufenden halten.
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/
Liebe Kitodo Entwickler,
durch den Start des DFG Projektes zur Weiterentwicklung von
Kitodo.Production ergeben sich Änderungen in der Branch-Struktur in GitHub.
Diese Änderungen werden in gleicher Form in den 3 GIT Repos
- Kitodo.Production [1]
- Kitodo.UGH [2]
- Kitodo.ContentServer [3]
erfolgen. Der Plan sieht vor, dass die Weiterentwicklung im Rahmes des
DFG Projektes im "master" Branch erfolgt. Im neuen Branch "2.x" wird die
kommende Version 2.0.0 und die darauf basierenden Versionen der
jeweiligen Teilprojekte von Kitodo.Production/UGH/ContentServer erfolgen.
Diese Änderung wird in den nächsten Tagen stattfinden. Ich werde vorher
die noch offenen Pull-Requests, die in beiden Branches Verwendung finden
noch vorher mergen.
Zukünftig ist darauf zu achten, dass die Pull-Requests gegen die jeweils
korrekte Entwicklung gestellt werden.
Viele Grüße
Henning Gerhardt
[1] https://github.com/kitodo/kitodo-production
[2] https://github.com/kitodo/kitodo-ugh
[3] https://github.com/kitodo/kitodo-contentserver
--
Henning Gerhardt
Sächsische Landesbibliothek -
Staats- und Universitätsbibliothek Dresden (SLUB)
Abt. Informationstechnologie (IT), Ref. Digitale Bibliothek
01054 Dresden
Besucheradresse: Zellescher Weg 18, 01069 Dresden
Tel.: +49 351 4677 227 | Fax: +49 351 4677 711
E-Mail: henning.gerhardt(a)slub-dresden.de
www.slub-dresden.de
