Re: [KitodoDev] Coding guidelines

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(a)slub-dresden.de www.slub-dresden.de<http://www.slub-dresden.de/> <mailto:jens.bemme@slub-dresden.de> | www.kitodo.org/ Von: kitodo-developer-bounces(a)kitodo.org [mailto:kitodo-developer-bounces@kitodo.org] Im Auftrag von Stefan Weil Gesendet: Dienstag, 20. Dezember 2016 17:57 An: kitodo-developer(a)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/8b2939f01a0a392e81c3f7d0f7bbe… 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