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