Coding und Security Grundsätze
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 openCode 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.
1. Coding Grundsätze – Open Source Kopiert!
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 openCode-Plattform erachtet werden.
1.1. Beitragen zu Projekten erleichtern Kopiert!
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 openCode 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 openCode in Form der GitLab-Issues, GitLab-Wiki und Discourse Verwendung finden.
1.2. Sicherstellung der Wiederverwendbarkeit und Portabilität Kopiert!
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:
- Überprüfen von Commits bzw. Beiträgen auf die Abwesenheit von situationsspezifischen Daten (bspw. aus einer Organisation)
- Austausch mit anderen Organisationen, die ähnliche Anforderungen haben
- Codebase wird in verschiedenen Kontexten eingesetzt
1.3. Allgemeine Anforderungen an Code Kopiert!
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.
1.4. Dokumentation Kopiert!
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 Expert:innen eingeholt werden, die die Verständlichkeit überprüfen. Ein weiteres Überprüfungskriterium stellt die Möglichkeit von Dokumentationsgeneration aus dem Code dar.
1.5. Verwendung von Lizenzen und öffentlichen Standards Kopiert!
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 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.
1.6. Sonstige Anforderungen Kopiert!
Eine zusätzliche Empfehlung ist die Verwendung der englischen Sprache in der Readme-Datei. Innerhalb der openCode-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 grundsätzlich empfohlen.
2. Security Grundsätze in der Kontribution Kopiert!
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.
2.1. Scanner auf Entwicklungssystemen Kopiert!
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.
2.2. Scanner in der Infrastruktur Kopiert!
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 openCode 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.
2.3. Keine intern verwendete Software ohne etablierte Releases veröffentlichen Kopiert!
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.
2.4. Sichere Pfade Kopiert!
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.
2.5. Zwischengeschaltetes Repository Kopiert!
Durch die Verwendung von zwischengeschalteten Repositories, etwa einem internen Repository zwischen dem Entwickelnden und dem openCode Repository, kann die direkte Entwicklerkommunikation in die Öffentlichkeit unterbunden werden und bietet einen zentralen Punkt für Reviews.
2.6. Trennung des Open Source und internen Projektes Kopiert!
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 openCode-Plattform sollte somit nur für die externe Kommunikation verwendet werden.
2.7. Vieraugenprinzip für größere Kontributionen Kopiert!
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.
2.8. Zusammenfassung Kopiert!
- Alle Informationen innerhalb eines Git-Repository können versehentlich veröffentlicht werden. Dateien, die außerhalb des Repository liegen, sind bei Git in der Regel vor versehentlicher Veröffentlichung geschützt.
- Die ungewollte Veröffentlichung von proprietärem Code birgt Risiken für die jeweiligen Institutionen. Das Vieraugenprinzip bei der Veröffentlichung größerer Kontributionen kann dem vorbeugen. Der Einsatz maschineller Prüfung durch spezielle Scanner bringt zusätzliche Sicherheit.
- Die Veröffentlichung von interner Kommunikation kann reputative und sicherheitstechnische Folgen haben. Links auf das Code Repository von openCode in der internen Dokumentation sollten explizit von internem Support und Kontaktstellen unterschieden werden.
- Zwischengeschaltete Code bieten einen Ort zum Experimentieren und operativen Quick-fixes für Projekte mit Nähe zum operativen Geschäft und hohem Entwicklungsstand.
3. Hilfen für das Schreiben wiederverwendbaren Codes Kopiert!
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.
3.1. Benennung Kopiert!
Die Benennung ist entscheidend für die Lesbarkeit des Codes für Außenstehende. Eine geeignete Wahl der Namen hilft dabei, die Funktion bzw. 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 bzw. 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 bzw. 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.
3.2. Verknüpfungen Kopiert!
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 ode ähnliches, 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.
4. Coding Best-Practices Kopiert!
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:
- Single-responsibility principle (SRP)
- Open-closed principle (OCP)
- Liskov substitution principle (LSP)Fkateg
- Interface segregation principle (ISP)
- Dependency inversion Principle (DIP)
Die Bedeutung der fünf Prinzipien ist im Folgenden erläutert. Eine mit Code Beispielen ergänzende Beschreibung kann unter dem Community Artikel [hier] eingesehen werden.
Single-responsibility principle (SRP)
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.
Open-closed principle (OCP)
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.
Liskov substitution principle (LSP)
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.
Interface segregation principle (ISP)
Viele kundenspezifische Schnittstellen sind einer Allzweckschnittstelle vorzuziehen. Dies führt zur Entkoppelung von Systemen, und die Programme sind leichter zu warten.
Dependency inversion principle (DIP)
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. 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 openCode 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.