Lieber Herr Weil,

ich hätte mich gefreut, die Anmerkungen zur Rechtschreibung schon in der ersten Runde zu bekommen, ich habe diese jetzt noch mit eingearbeitet und hoffe, dass es vorerst keine weiteren Änderungswünsche gibt.
Eine Erarbeitung der Coding Guidelines in markup ist sicher eine gute Idee für die Zunkunft, doch aktuell liegen diese nur im PDF Format vor, so dass mir eine Verbreitung per Mail am sinnvollsten erschien. Die Änderungen hatte ich in der Initialen Mail gesondert beschrieben und die Motivation erklärt.

Sicher können die Coding Guidelines gekürzt werden. Wir haben uns aber vorerst auf die Anpassungen konzentriert, die unsere Entwicklung direkt betreffen. Zum kompletten Überarbeiten, Kürzen und Umformulieren haben wir aktuell keine Zeit.

Zum Thema Exceptions:

Diese sollten nicht Teil des normalen Programmcodes sein. Und selbst wenn dies bereits der Fall ist, sollte ein Log vermerken, dass diese Exception erwartet ist.

Auch fremder Code sollte kein Teil von Kitodo Production sein. Entweder wir nutzen libraries, welche nicht formatiert werden, oder wir schreiben Funktionalität selbst. Sollte fremder Code in Kitodo Production übernommen werden, so sollte dieser auch mit dem Codeformatter formatiert werden, da er damit auch Bestandteil unserer Codebasis wird.

Leider ist nun die Abstimmung der Mitgliederversammlung in der Satzung festgelegt, so dass wir diesen Weg gehen müssen. Eine Änderung das Satzung diesbezüglich ist natürlich wünschenswert und sollte demnächst angestrebt werden.

Im Anhang nochmal das Dokument mit geänderten Leerzeichen.

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/

Von: kitodo-developer-bounces@kitodo.org [mailto:kitodo-developer-bounces@kitodo.org] Im Auftrag von Stefan Weil
Gesendet: Dienstag, 20. Dezember 2016 17:57
An: kitodo-developer@kitodo.org
Betreff: Re: [KitodoDev] Coding guidelines

Am 20.12.2016 um 12:43 schrieb Huber, Kathrin:

Liebe Entwickler,

nach unserem Vorschlag der Änderungen zu den Coding Guidelines, habe ich nun die angebrachten Punkte eingearbeitet. Ihr findet im Anhang das neue Dokument. Wenn es eurerseits keine Einwände gibt, werde ich dieses an den Kitodo Vorstand zur Absegnung schicken. Ab diesem Zeitpunkt werden wir nach den neuen Guidelines entwickeln.
Rückmeldungen bitte bis zum 11.01.2017.

Liebe Grüße

Kathrin Huber

Digitale Bibliothek

Liebe Frau Huber,

hier ein paar kleine Hinweise zur Form:

* Die Abkürzung schreibt sich korrekt z. B. (nicht z.B.).
* Gleiches gilt für e. V. (nicht e.V.).
* Auch nach dem Paragraphzeichen folgt ein Leerzeichen, also § 3.5.

Zum Inhalt selbst:

Ich glaube, dass für Rückmeldungen zu einer mehrseitigen
PDF-Datei mit eventuell anschließender Diskussion E-Mails
nicht das optimale Medium sind. Besser geeignet wären
beispielsweise GitHub (setzt Text als Markup voraus) oder
auch Google Docs. In GitHub lassen sich Änderungen auch
sehr übersichtlich darstellen. Hier ein Beispiel aus den
Praxisregeln Digitalisierung:

https://github.com/zuphilip/dfg-12-151/commit/8b2939f01a0a392e81c3f7d0f7bbe9a6c7f89ba0?short_path=4cd65fa#diff-4cd65faa2464fd51cf1567ae298f3117

Vielleicht können wir das bei zukünftigen Änderungen
so handhaben.

Generell könnte der gesamte Text deutlich verkürzt werden,
da manche Aussagen überflüssig, unverständlich oder sogar
widersprüchlich sind und vieles meiner Ansicht nach gar
keiner formalen Regelung bedarf.

Ein Beispiel:

"verläuft sie negativ, geben sie den Entwicklungszweig
zur Nachbearbeitung an die Entwickler zurück".

Ich muss gestehen, dass ich das weder als Manager noch
als Entwickler verstehe (auch wenn ich weiß, was eigentlich
gemeint ist). Mir würde ohne diesen Satzteil nichts fehlen.
Möglicherweise stammt die Aussage noch aus einer Zeit,
wo Versionsverwaltung mit Sperren arbeitete.

Meine Anmerkungen zu Exceptions sind in die neue Version
nicht eingegangen. War das Absicht oder Versehen?

Ebenfalls unbeantwortet ist meine Frage bezüglich
Formatierung von fremden Code - oder habe ich die
Antwort übersehen?

Neue Anmerkungen:

Die GitHub-URL ist https://github.com/kitodo. Die im Dokument
angegebene Schreibweise mit Großbuchstaben funktioniert, führt
aber nach wenigen Klicks zur Verwirrung, da dann plötzlich alles
klein geschrieben ist.

"Diese Vereinbarungen gelten unabhängig von der verwendeten
Programmiersprache und für alle Komponenten der Kitodo Suite
gleichermaßen." Das stimmt vermutlich nur mit der Ergänzung
"soweit für die einzelne Komponente nichts anderes festgelegt
ist." - oder ist garantiert, dass beispielsweise die Richtlinien für
TYPO3 nie im Widerspruch zu den allgemeinen Richtlinien von
Kitodo stehen?

Wenn die Guidelines schon definieren, wie sicherheitskritische
Fehler zu melden sind, müssten sie konsequenterweise auch
die zugehörigen Programmänderungen behandeln. Die wird
man nämlich i. d. R. nicht öffentlich als Pull Request diskutieren,
was aber im Widerspruch zur zwingenden Forderung eines
Pull Requests steht.

Und eine letzte Anmerkung, die ich schon mehrfach geäußert
habe, aber gerne wiederhole: nach meiner Ansicht sind
Details von Programmierrichtlinien kein Thema für Vereinsvorstände
und Mitgliederversammlungen. Diese Gremien geben natürlich
gewisse Grundsätze vor, haben aber ansonsten Wichtigeres
zu tun als über Einrücktiefen, Camel Cases und Linefeeds zu
befinden.

Viele Grüße
Stefan Weil