Mit einer starken Orientierung an Best-Practices sowie dem „Standard for Public Code“, herausgegeben von der „Foundation for Public Code“, welche sich mit der Entwicklung und Pflege von Code im öffentlichen Sektor sowie allgemeinen Qualitätskriterien an Software auseinandersetzt, bildet diese Seite eine Hilfestellung dafür, wie die Teilnahme an Open CoDE für die Teilnehmer sicher gestaltet werden kann.
Die Grundsätze sollen eine Möglichkeit bieten, besseren und wartbareren Code zu erzeugen, mehr Mehrwert durch die eigene Kontribution zu schaffen und Sicherheitsprobleme im Zusammenhang mit Kontributionen zu adressieren. Diese Grundsätze sind nicht verbindlich und können auf freiwilliger Basis als qualitätssteigernde und risikoreduzierende Vorschläge umgesetzt werden.
Der „Standard for Public Code“ stellt eine Reihe von Kriterien auf, die öffentliche Einrichtungen und Organisationen beim Entwickeln und Instandhalten von Software unterstützen. Es wurden die Ziele, Methoden und Verifikationsmöglichkeiten übernommen, die als am stärksten anwendbar und mehrwertbringend für die Open CoDE Plattform erachtet werden.
Um für Projekte möglichst viele Beitragsleistende zu gewinnen, sollen Vertrauen in die Plattform und der Community-Zusammenhalt innerhalb der Projekte gestärkt werden.
Zur Erreichung dieser Ziele soll jedes Projekt einen Contribution Leitfaden bereitstellen, bspw. in Form einer CONTRIBUTING-Datei. Diese soll Entwickelnden als Handreichung dienen, wie sie zu einem Projekt beitragen können. Darüber hinaus soll eine öffentliche Roadmap verfügbar sein, die die wesentlichen Entwicklungsziele und den Zeitrahmen für das Projekt aufzeigt.
Für das Einreichen von Verbesserungsvorschlägen ist ein Issue Tracker zur Verfügung zu stellen, welcher allen Teilnehmenden der Plattform zugänglich ist – hier kann das Angebot des Code Repository von Open CoDE in Form der GitLab Issue Tracker verwendet werden. Die Meldung von Security-relevanten Issues sollte über einen nicht öffentlichen Kanal möglich sein.
Zur Steigerung des Austauschs zwischen Nutzenden und Entwickelnden bietet sich das Bereitstellen von Kommunikationskanälen an – hier kann unter anderem das Angebot des Code Repository von Open CoDE in Form der GitLab-Issues, GitLab-Wiki und Discourse Verwendung finden.
Innerhalb von Projekten soll ein möglichst hoher Grad an Wiederverwendbarkeit und Portabilität geschaffen werden. Dies dient dem Ziel, andere an den eigenen Entwicklungen teilhaben zu lassen und durch Wiederverwendung auch Dritte für die Mitarbeit am Projekt zu gewinnen, was wiederum die Qualität und Zuverlässigkeit des Projekts steigert.
Darüber hinaus sollen redundante Entwicklungen verhindert werden. Zur Erreichung dieses Ziels soll die Entwicklung der Codebase immer mit dem klaren Gedanken der Wiederverwendbarkeit in verschiedenen Kontexten getrieben werden. Die Codebase muss unabhängig und frei von Geheimnissen, proprietären, nicht-offenen Lizenzen oder nicht-offenem Code sein, um die potenzielle Basis der Nutzenden möglichst breit zu halten.
Nach Möglichkeit sollten die Bedürfnisse von mehr als einer Interessensgruppe in die Roadmap eines Projektes einfließen und die Codebase von mehr als einer Gruppe bzw. Organisation verwendet werden.
Als Indikatoren zur Verifikation der Ziele dienen:
Eine Menge von Anforderungen an neu entwickeltem Code soll sicherstellen, dass die Codebase gut wartbar ist und Probleme schnell identifiziert werden können. Darüber hinaus sollen neue Beitragsleistende zügig ein gutes Verständnis für die bisherige Codebase entwickeln können und ein hohes Entwicklungstempo ermöglicht werden.
Für diese Ziele sollen mehrere Kriterien beachtet werden. Alle größeren Funktionalitäten müssen automatisiert getestet werden können. Neue Beiträge zu einem Projekt müssen ein Review Verfahren (z.B. Pull Request) und erfolgreich sämtliche vorhandenen Software Tests durchlaufen. Darüber hinaus sollten Beiträge klein und verständlich gehalten werden.
Weitere Gütekriterien wie Source Code Test Coverage zur Sicherstellung einer weitreichenden Testabdeckung des Programmes und Dokumentations Coverage zur Sicherstellung einer weitreichenden Dokumentation des Codes und der Funktionen sollte laufend überwacht werden. Hierbei wird (in der Regel automatisiert) ein Indikator für das Einhalten dieser Prinzipien angewendet und projektweit dargestellt.
Die Dokumentation des Projektes und der Codebasis sind essenziell. Sie senken die Einstiegshürde für Beitragsleistende und Nutzende des Projekts. Des Weiteren sorgen sie für eine höhere Projekttransparenz.
Wichtige Bestandteile guter Dokumentation sind u.a. Anweisungen zur Installation und Ausführung des Source Codes, Beispiele für die Verwendung von Kernfunktionalitäten und Dokumentation über alle Funktionalitäten.
Darüber hinaus bietet sich das Vorhandensein einer für ein breiteres Publikum bestimmten, allgemeineren Dokumentation an, welche high-level Konzepte des Projekts beschreibt. Von Vorteil ist außerdem die Zurverfügungstellung einer Stand-Alone Version, welche mit bereitgestellten Testdaten von Interessenten benutzt werden kann.
Zur Überprüfung der Dokumentationsqualität und des Dokumentationsumfangs können Urteile von Stakeholdern und Professionals eingeholt werden, die die Verständlichkeit überprüfen. Ein weiteres Überprüfungskriterium stellt die Möglichkeit von Dokumentationsgeneration aus dem Code dar.
Die Verwendung bestimmter Lizenzen und der Einsatz öffentlicher Standards innerhalb von Projekten soll Interoperabilität zwischen Systemen sicherstellen, die Unabhängigkeit von Vendoren garantieren und jedem das Recht geben, den Code zu sichten und direkt ersichtlich zu machen, wie der Code weiter benutzt werden darf.
Hierzu ist es notwendig, dass sämtlicher Code und sämtliche Dokumentation unter einer den OSI (Open Source Initiative) Anforderungen entsprechenden Lizenz von der Plattform freigegeben wurde, sodass eine freie Weiterbenutzung, Änderung und Weiterverbreitung möglich sind. Für den gesamten Source Code sollte auf Dateiebene jeweils eine Lizenz angegeben werden, soweit möglich als maschinenlesbare License und Copyright Header.
Code, der die Funktionalität des Datenaustauschs hat, soll einen öffentlichen Standard für den Austausch verwenden, innerhalb der Codebase sollte eine Liste aller dieser verwendeten Standards existieren.
Zur Verifikation dieser Punkte können Tools wie bspw. REUSE eingesetzt werden.
Eine zusätzliche Empfehlung ist die Verwendung der englischen Sprache. Innerhalb der Open CoDE Plattform ist sowohl Deutsch innerhalb der Programme und Dokumentationen als auch Englisch akzeptiert. Um jedoch mit der europäischen und internationalen Gemeinschaft kollaborieren zu können sowie einheitliche Begriffe in verschiedensprachigen Komponenten innerhalb Software Stacks anzuwenden, wird die Verwendung der englischen Sprache empfohlen.
Um einen sicheren Raum der Kollaboration zu schaffen, werden im Folgenden Security Grundsätze für die Teilnehmenden beschrieben. Ziel der Sicherheitsmaßnahmen für Teilnehmende ist es, einen sicheren Raum für die Kontribution zu schaffen und Sicherheitsrisiken, die durch die Kontribution entstehen, zu vermeiden.
Sicherheitsrisiken für Teilnehmende entstehen in der Regel durch die unbewusste Veröffentlichung von geheimen Informationen wie Passwörter und Tokens sowie der versehentlichen Veröffentlichung von internen Informationen und Programmen. Erhöht ist das Risiko zudem, wenn die Komponente im internen Einsatz ist. Um dem Verlust von Geheimnissen vorzubeugen, sollten technische und organisatorische Maßnahmen ergriffen werden.
Die grundsätzliche Verwendung von Secret-Scannern in Kombination mit Open Source Kontributionen wird empfohlen. Hierbei können Client-seitige Werkzeuge wie GitLeaks und Git-Secrets Verwendung finden.
Die Verwendung von Repositoryscannern wie GitLabs Secret Detection kann Teilnehmenden das Risiko der durch fehlkonfigurierte Entwicklungsmaschinen veröffentlichten Geheimnisse reduzieren. Hierbei ist zu beachten, dass Token Scanner der Infrastruktur und somit des Code Repository von Open CoDE die Informationen erst nach oder während der versehentlichen Veröffentlichung detektieren können. Aus Sicherheitsgründen kann somit frühzeitig gewarnt und auf Veröffentlichung hingewiesen werden, jedoch bietet dies keinen Schutz vor der eigentlichen Veröffentlichung.
Software aus der internen Verwendung, welche ohne feste Releases betrieben wird, birgt ein erhöhtes Risiko versehentlicher Veröffentlichung von Geheimnissen, da kurzfristig notwendige operative Anpassungen oft nicht ausreichend vor dem Einpflegen überprüft werden. Für Projekte mit hoher interner Aktivität und ohne Releases wird empfohlen, mindestens ein zwischengeschaltetes Repository für kurzfristige Änderungen zu verwenden.
Eine grundlegende Empfehlung des Repository ist es, keine Geheimnisse, auch temporär, innerhalb eines Git-Repository auf Entwicklungsmaschinen zu verwenden. Projekte innerhalb der Plattform, insbesondere jene mit Netzwerkkommunikation, sollten die Verwendung von außerhalb des Verzeichnisses liegenden Geheimnissen erleichtern und die im Projekt verwendeten Konfigurationsdateien explizit über den gitignore-Mechanismus blockieren.
Durch die Verwendung von zwischengeschalteten Repositories, etwa einem internen Repository zwischen dem Entwickelnden und dem Open CoDE Repository, kann die direkte Entwicklerkommunikation in die Öffentlichkeit unterbunden werden und bietet einen zentralen Punkt für Reviews.
Die Open Source Projekte innerhalb der Plattform entspringen oft direkten kommunalen Anwendungsfällen. Den internen Anwendenden der Software sollte weiterhin der interne Kommunikationspfad offenstehen, da nicht allen Teilnehmenden der öffentliche Charakter des Open Source Repository bewusst ist. Die Open CoDE Plattform sollte somit nur für die externe Kommunikation verwendet werden.
Bei größeren Kontributionen, üblicherweise jene, die nicht auf eine Bildschirmseite passen, inhaltlich nicht überschaubar oder auf Geräten mit sensiblen Daten entstanden sind, wird ein Vieraugenprinzip empfohlen. Insbesondere bei größeren und damit möglicherweise nicht vollständig eigenständig durch den Veröffentlichenden erstellten Kontributionen sollte der Inhalt dieser Prüfung neben dem eigentlichen Code auch den Ursprung des zu veröffentlichen Codes umfassen, sowie etwaige Kommentare und Inhalte von Commit-Messages berücksichtigen.
Neben den übergeordneten Prinzipien für das Entwickeln von Software in der OS-Umgebung, sollten auf detaillierterer Ebene verschiedene Regeln für das saubere Schreiben von Code beachtet werden. Dabei geht es zum einen um die Art, wie Benennungen vorgenommen werden sollten und zum anderen, wie Verknüpfungen zu formulieren sind. Die Wahl von Bezeichnungen und die Formulierung der Verknüpfungen im Quellcode haben großen Einfluss auf die Lesbarkeit des Codes. Im Ergebnis ist der Code schneller verständlich und seine Funktion/Logik von außen leichter zu beurteilen.
Die Benennung ist entscheidend für die Lesbarkeit des Codes für Außenstehende. Eine geeignete Wahl der Namen hilft dabei, die Funktion/Logik eines Programms zu beurteilen.
Variablen sollten so benannt werden, dass ihre Funktion offensichtlich ist. Die Namen sollten durch die Suche leicht zu finden sein. Dies bedeutet, Benennungen wie <a> sind ungeeignet, da sie weder erklärend noch garantiert einfach durch die Suche zu finden sind (<a> ist möglicherweise in anderen Bezeichnungen enthalten). Ebenso wenig aussagekräftig sind Benennungen wie <table>.
Bei Klassen sollten für den Namen Nomen statt Verben verwendet werden. Wie oben beschrieben, sollte eine Klasse immer nur eine Funktion erfüllen. Somit sollte der Name immer nur eine Funktion beschreiben. Akronyme und Abkürzungen sollten zur Benennung nur dann verwendet werden, wenn sie allgemein geläufig sind.
Für die Benennung von Funktionen/Methoden sollten in Abgrenzung zu Klassen Verben und keine Nomen verwendet werden. Sie sollten erklärend sein. Daher sind generische Bezeichnungen wie <start> zu vermeiden. Längere Bezeichnungen sind akzeptabel, solange sie den Zweck der Funktion/Methode klar definieren.
Da Wahrheitswerte (Booleans) nur zwei Ausprägungen (true und false) annehmen können, sollte sich dies in der Bezeichnung widerspiegeln. Hierfür eignen sich zusammengesetzte Namen aus is/has/can und Nomen/Adjektiven, wie z.B. <isAdmin>.
Weitere Regeln lauten wie folgt: Es sollten nicht mehrere Begriffe für das gleiche Konzept einer Funktion verwendet werden (z.B. get/pick/etc.). Ebenso sollte nicht ein Begriff für mehrere Konzepte von Funktionen gebraucht werden (z.B. substract für Subtraktion im mathematischen Sinn und Entnahme aus einer Liste). Weiter sollten Namen aussprechbar sein, um mit anderen Plattformteilnehmenden darüber diskutieren zu können. Bezeichnungen sind außerdem so zu wählen, dass sie inhaltlich klar unterscheidbar sind.
Implizite Vergleiche sind expliziten vorzuziehen. Vergleiche mit true oder false sind überflüssig und füllen den Code optisch unnötig.
Die Verwendung von impliziten Zuweisungen (z.B. Zuweisung eines Wahrheitswertes ohne die Verwendung von if-else-Schleifen) reduziert die Anzahl an Zeilen und erhöht so die Übersichtlichkeit, während die Fehlermöglichkeiten reduziert werden.
Es sollten bevorzugt positive Verknüpfungen formuliert werden. Dies verbessert die Lesbarkeit und reduziert die kognitive Anstrengung des Lesenden.
Die Verwendung ternärer Operatoren reduziert, ebenso wie die Verwendung impliziter Zuweisungen, die Anzahl an Zeilen und erhöht so die Übersichtlichkeit, während die Fehlermöglichkeiten reduziert werden.
Sogenannte Magic Strings/numbers (typischerweise Elemente zum Zwischenspeichern o.ä., die in der Regel nicht von außerhalb aufgerufen werden) sollen vermieden werden. Sie verschlechtern die Lesbarkeit und begünstigen Schreibfehler, da sie die automatische Vervollständigung nicht unterstützen. Sie sind außerdem als Element nicht suchbar.
Eine Bevorzugung deklarativer gegenüber imperativen Formulierungen ist anzustreben, um die Fehleranfällig zu verringern und die Lesbarkeit zu erhöhen. Deklarative Formulierungen geben an, was die Funktion eines Code-Abschnitts ist. Imperative Formulierung zeigen, wie die Ausführung einer Funktion funktioniert.
Um eine verständliche, wiederverwendbare, testbare, wartungsfähige und flexible Codebase zu erreichen, werden verschiedene übergreifende Prinzipien der Softwareentwicklung nach Robert C. Martin beschrieben.
Die Grundprinzipien orientieren sich nach dem Akronym SOLID und lauten:
Die Bedeutung der fünf Prinzipien ist im Folgenden erläutert. Eine mit Code Beispielen ergänzende Beschreibung kann unter dem Community Artikel [hier, extern] eingesehen werden.
Jede Klasse oder Modul eines Programms ist für die Ausführung genau einer Funktion verantwortlich (engl. responsible). So sind die Module leichter verständlich und lesbar. Es erleichtert außerdem die Wartung, da klarer ist, welcher Teil eines Programms durch eine Veränderung beeinflusst wird.
Software Einheiten sind so aufzubauen, dass sie offen für Erweiterungen sind, jedoch für neue Funktionen nicht modifiziert werden müssen, also in sich geschlossen sind. Dies stellt die Wiederverwendbarkeit und Wartungsfähigkeit sicher und erhöht die Robustheit der Programmierung.
Programme müssen weiterhin lauffähig bleiben, wenn Objekte dieser Programme durch Instanzen ihrer Untertypen substituiert werden. Dies erhöht die Wiederverwendbarkeit von Programmierungen und erleichtert das Verständnis ihrer Hierarchien.
Viele kundenspezifische Schnittstellen sind einer Allzweckschnittstelle vorzuziehen. Dies führt zur Entkoppelung von Systemen, und die Programme sind leichter zu warten.
Module sollten nur von Modulen höherer Ebenen abhängen. Demnach können nur Abhängigkeiten von internen Details, etwa Variablen und Funktionen auf Abstraktionen höherer Ebenen abhängen, jedoch nicht umgekehrt.