Hallo Kathrin, Jetzt ist der Bezug verloren gegangen: “Diese sind […] an security(a)kitodo.org zu senden. Auch Entwicklungsvorhaben sind immer dort zu dokumentieren.” Sicherlich war gemeint: “Entwicklungsvorhaben sind immer auf GitHub zu dokumentieren.” Gruß Matthias Ronge ________________________________ Matthias Ronge Software Entwicklung/Software Development [cid:Z_Logo_RGB_180px_2b974e26-85b9-4005-92dd-9bb8df881ab3.png]<http://www.zeutschel.de> <http://www.zeutschel.de> [cid:Facebook-34x34_ab94d89a-875f-49f2-81f3-e136c66e4bb5.png]<https://www… [cid:Twitter-34x34_f9819937-1c34-4eab-b2fc-944fcf2e8938.png]<https://twit… [cid:YouTube-34x34_8cf03759-cc15-472e-a763-e628ea59d43b.png]<http://www.y… [cid:google_34x34_daf218c4-f635-49e8-af7a-ed2a74c251ea.png]<https://plus.… Zeutschel GmbH | Heerweg 2 | 72070 Tübingen | Deutschland p: +49 (7071) 9706-62 | m: | f: +49 (7071) 9706-44 e: Matthias.Ronge@zeutschel.de<mailto:Matthias.Ronge@zeutschel.de> | w: http://www.zeutschel.de [cid:zeta-banner-86x75_fuerWebsite_c5e46c08-490e-49fa-b13f-d59217ddd169.png]<http://www.zeutschel.de/links/Zeta-App> Geschäftsführer/President: Joerg Vogler | Registergericht Stuttgart: HRB 380917 From: kitodo-developer-bounces(a)kitodo.org [mailto:kitodo-developer-bounces@kitodo.org] On Behalf Of Huber, Kathrin Sent: Tuesday, December 20, 2016 2:52 PM To: kitodo-developer(a)kitodo.org Subject: Re: [KitodoDev] Coding guidelines Vielen Dank Matthias für dein Feedback! Das sind zwei sehr gut Punkte, die ich direkt geändert habe. Dass GitHub ein „SecurityIssue“-Feature nicht unterstützt war mir nicht bewusst. Das schein ein Relikt aus der Launchpad Zeit zu sein, wo dies möglich war. Wir werden eine security@kitodo.org<mailto:security@kitodo.org> E-Mail Adresse einrichten, durch welche die Releasemanager informiert werden. 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<mailto:kathrin.huber@slub-dresden.de> www.slub-dresden.de<http://www.slub-dresden.de/> <mailto:jens.bemme@slub-dresden.de> | www.kitodo.org/<http://www.kitodo.org/> Von:kitodo-developer-bounces@kitodo.org<mailto:kitodo-developer-bounces@kitodo.org> [mailto:kitodo-developer-bounces@kitodo.org] Im Auftrag von Ronge, Matthias Gesendet: Dienstag, 20. Dezember 2016 14:24 An: &#39;kitodo-developer(a)kitodo.org&#39; Betreff: Re: [KitodoDev] Coding guidelines Hallo Entwickler, Zwei Kleinigkeiten sind mir noch aufgefallen: Ø ‘Klasse Foo, Package org.Kitodo.bar: /src/org/Kitodo/bar/Foo.java’ (S. 4 oben) Package-Namen schreibt man in Java im Allgemeinen in Kleinbuchstaben. Das würde ich hier genauso durchziehen, also ‘Klasse Foo, Package org.kitodo.bar: /src/org/kitodo/bar/Foo.java’ Ø Github bietet meines Wissens keine Möglichkeit, sicherheitskritische Fehler (‘verdeckt’) zu melden [1]. Ich bitte um Aufklärung, falls sich das geändert haben sollte. Gruß Matthias Ronge __________ 1) http://opensource.stackexchange.com/q/1958 From:kitodo-developer-bounces@kitodo.org<mailto:kitodo-developer-bounces@kitodo.org> [mailto:kitodo-developer-bounces@kitodo.org] On Behalf Of Huber, Kathrin Sent: Tuesday, December 20, 2016 12:43 PM To: kitodo dev (kitodo-developer@kitodo.org<mailto:kitodo-developer@kitodo.org>) Subject: [KitodoDev] Coding guidelines 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 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<mailto:kathrin.huber@slub-dresden.de> www.slub-dresden.de<http://www.slub-dresden.de/> <mailto:jens.bemme@slub-dresden.de> | www.kitodo.org/<http://www.kitodo.org/>

Am 04.01.2017 um 14:38 schrieb Huber, Kathrin: Liebe Frau Huber, mit Pandoc (http://pandoc.org/) sollte die Konvertierung von docx nach md funktionieren, wobei vermutlich noch etwas Handarbeit anschließend nötig sein wird. Wenn Sie mir den Leitfaden als Word-Datei schicken, kann ich das gerne mal ausprobieren. Und wenn Sie auch noch die alte(n) Version(en) haben, wäre sogar ein komfortabler Versionsvergleich auf GitHub möglich. Viele Grüße Stefan Weil

Liebe Entwickler, Die Vermeidung von Exceptions im regulären Programmablauf ist aus vielerlei Gründen anzustreben. Einer ist, dass ihre Verarbeitung vom Compiler bzw. JIT vergleichsweise schlecht optimiert wird, was ja auch logisch erscheint: Wenn das Kind bereits in den Brunnen gefallen ist (z.B. kein Arbeitsspeicher mehr frei) sollte man nicht mehr unnötig herumspielen (was möglicherweise zusätzlich Speicher allokiert), das macht die Sache tendenziell eher schlimmer. Es macht auch keinen Sinn, wenn eine Anwendung im regulären Betrieb 200 Exceptions in der Minute loggt; mit dem Logfile kann man auch keine Fehlerdiagnose mehr durchführen, weil man die wahren Probleme dann darin auch nicht mehr findet. Ein anderer Grund ist, dass es in Eclipse (in anderen IDEs wahrscheinlich ebenfalls) einen Schalter gibt, dass die Anwendung bei jeder auftretenden Exception anhält. Auch das kann man nicht mehr nutzen, wenn Exceptions im Regelbetrieb andauernd geworfen werden. Manchmal braucht man, um das sinnvoll umzusetzen, mehrere Methoden, etwa zum Holen eines Parameters aus der Konfiguration: eine, die eine Exception wirft, und eine andere, die es nicht tut. String getString(String key); // wirft eine NoSuchElementException, wenn es den Parameter nicht gibt String getString(String key, @Nullable String orElese); // gibt den Defaultwert zurück, wenn es den Parameter nicht gibt Auch in dem Fall sollte die Reihenfolge entsprechend sein, also getString(String) ruft getString(String, String) auf: String getString(String key) { String result = getString(key, null); if (result == null) { throw new NoSuchElementException(“No configuration entry for key: ” + key); } return result; } Und nicht andersherum (getString(String, String) ruft getString(String) auf): String getString(String key, @Nullable String orElse) { try{ return getString(key); } catch(NoSuchElementException noSuchKey){ logger.info(noSuchKey.getMessage() + “, using default value ” + orElse, e); return orElse; } } In diesem Blog gibt es gleich mehrere gute Artikel zu Java Exceptions: http://howtodoinjava.com/category/core-java/exception-handling/ Grüße Matthias Ronge ________________________________ Matthias Ronge Software Entwicklung/Software Development [cid:Z_Logo_RGB_180px_2b974e26-85b9-4005-92dd-9bb8df881ab3.png]<http://www.zeutschel.de> <http://www.zeutschel.de> [cid:Facebook-34x34_ab94d89a-875f-49f2-81f3-e136c66e4bb5.png]<https://www… [cid:Twitter-34x34_f9819937-1c34-4eab-b2fc-944fcf2e8938.png]<https://twit… [cid:YouTube-34x34_8cf03759-cc15-472e-a763-e628ea59d43b.png]<http://www.y… [cid:google_34x34_daf218c4-f635-49e8-af7a-ed2a74c251ea.png]<https://plus.… Zeutschel GmbH | Heerweg 2 | 72070 Tübingen | Deutschland p: +49 (7071) 9706-62 | m: | f: +49 (7071) 9706-44 e: Matthias.Ronge@zeutschel.de<mailto:Matthias.Ronge@zeutschel.de> | w: http://www.zeutschel.de [cid:zeta-banner-86x75_fuerWebsite_c5e46c08-490e-49fa-b13f-d59217ddd169.png]<http://www.zeutschel.de/links/Zeta-App> Geschäftsführer/President: Joerg Vogler | Registergericht Stuttgart: HRB 380917 From: kitodo-developer-bounces(a)kitodo.org [mailto:kitodo-developer-bounces@kitodo.org] On Behalf Of Huber, Kathrin Sent: Wednesday, January 4, 2017 2:39 PM To: kitodo-developer(a)kitodo.org Subject: 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@slub-dresden.de<mailto:kathrin.huber@slub-dresden.de> www.slub-dresden.de<http://www.slub-dresden.de/> <mailto:jens.bemme@slub-dresden.de> | www.kitodo.org/<http://www.kitodo.org/> Von: kitodo-developer-bounces@kitodo.org<mailto: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<mailto: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/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

Die Coding Guidelines haben vorher schon vorgeschrieben, dass alle Exceptions in den Log geschrieben werden müssen. Wenn dieser Regel konsequent gefolgt worden wäre, vielleicht gäbe es dann nicht so viele Exceptions, die Teil des normalen Programmablaufs sind. Ich kann mich nur wiederholen: Wenn eine Exception Teil des Programablaufs ist, sollte gerade dann geloggt werden, warum, damit andere Entwickler die Entscheidung nachvollziehen und gegebenenfalls verbessern können. Ich denke es ist keine schlechte Idee, alle bestehenden Exceptions um Protokollierung zu ergänzen, denn Ziel ist es ja eine saubere Codebasis zu haben und diese Stellen zu entfernen. 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: Donnerstag, 5. Januar 2017 10:37 An: kitodo-developer(a)kitodo.org Betreff: Re: [KitodoDev] Coding guidelines Am 05.01.2017 um 09:32 schrieb Ronge, Matthias: Die Vermeidung von Exceptions im regulären Programmablauf ist aus vielerlei Gründen anzustreben. Einer ist, dass ihre Verarbeitung vom Compiler bzw. JIT vergleichsweise schlecht optimiert wird, was ja auch logisch erscheint: Wenn das Kind bereits in den Brunnen gefallen ist (z.B. kein Arbeitsspeicher mehr frei) sollte man nicht mehr unnötig herumspielen (was möglicherweise zusätzlich Speicher allokiert), das macht die Sache tendenziell eher schlimmer. Es macht auch keinen Sinn, wenn eine Anwendung im regulären Betrieb 200 Exceptions in der Minute loggt; mit dem Logfile kann man auch keine Fehlerdiagnose mehr durchführen, weil man die wahren Probleme dann darin auch nicht mehr findet. Ein anderer Grund ist, dass es in Eclipse (in anderen IDEs wahrscheinlich ebenfalls) einen Schalter gibt, dass die Anwendung bei jeder auftretenden Exception anhält. Auch das kann man nicht mehr nutzen, wenn Exceptions im Regelbetrieb andauernd geworfen werden. Liebe Mitentwickler, nur zur Klarstellung: auch ich sehe das so, dass Exceptions für den regulären Programmablauf vermieden werden sollten. Folgendes hatte ich angemerkt: Die Protokollierungspflicht sollte präzisiert werden: es gibt heute schon Code, bei dem Exceptions Teil des normalen Programmablaufs sind. Da wäre eine Protokollierung kontraproduktiv, da sie unnötig Ressourcen kostet. Textvorschlag: "Unerwartete Exceptions müssen immer im Log registriert werden" Auf Basis der unglücklich formulierte Coding Guidelines ("Sie [Exceptions] müssen immer im Log registriert werden") könnte jemand auf die Idee kommen, alle Exceptions um Protokollierung zu ergänzen. Das wäre sehr schlecht. Liebe Frau Huber, es ist keine böse Absicht, wenn ich Ihnen Rechtschreibfehler spät melde, sondern es liegt einfach daran, dass ich sie auch erst spät bemerke. Gerade jetzt habe ich wieder einen, der korrigiert werden sollte: "Exeptions". Übrigens wäre es mit der Word-Datei einfacher, solche Fehler zu finden. Viele Grüße Stefan Weil PS. Es ist eine gute, aber leider noch zu wenig verbreitete Sitte, in Beiträgen zu Mailinglisten die Antworten um unnötigen Ballast zu kürzen, also nicht einfach alle früheren Beiträge wieder mitzuschicken.

Am 05.01.2017 um 11:07 schrieb Stefan Weil: Sorry, das war ein falscher Alarm (Nebeneffekt meiner Konvertierung von PDF nach Word). Gruß, Stefan Weil