Texte: Programmier-Richtlinien

Ich möchte behaupten, dass es fast soviele Programmier-Stile wie Programmierer gibt, denn oft entwickeln Programmierer im Laufe der Zeit Eigenheiten, die ggf. irgendwann zu Problemen führen, sobald man mit anderen im Team arbeiten muss.

Deshalb wurden Programmier-Richtlinien entwickelt, die dabei helfen sollen, dass Programmierer A den Quellcode von Programmierer B lesen und verstehen kann. Leider gibt es jedoch sehr viele verschiedene Richtlinien, die von Firma zu Firma und von Programmiersprache zu Programmiersprache unterschiedlich ausgelegt werden.

Dies ist einerseits schade, da es so doch wieder verschiedene Stile gibt und die Arbeit immer eine gewisse Eingewöhnungsphase erfordert, um mit den Regeln "warm" zu werden.
Andererseits gibt einem das die Möglichkeit, Standard-Richtlinien lediglich als Vorlage zu nutzen und seinen eigenen Ansprüchen anzupassen.

Auch ich habe im Laufe der Zeit die zahlreichen im Studium erlernten Standards zusammengewürfelt und dabei meinen eigenen Standard entwickelt, mit dem ich sehr gut zurechtkomme und der auch alltagstauglich ist.

Hier nun meine Programmier-Richtlinien, die natürlich auf die Web-Programmierung zugeschnitten wurden und gerne (auch nur in Teilen) übernommen werden dürfen:


Die Programmierumgebung
1.
Für die Programmierung wird ein Text-Editor verwendet. WYSIWYG-Editoren sind nicht zulässig, da sie meist mehr Code produzieren, als notwending ist. Ausserdem sollte sich ein Programmierer nicht auf Vorlagen verlassen, sondern muss mit einem leeren Blatt beginnen können.



2.
Um einen geordneten Ablauf zu gewährleisten, wird eine Versionsverwaltung (siehe bspw. Tortoise SVN) genutzt:
  • Skript(e) aus dem Projektarchiv (Repository) laden und sperren
  • Änderungen auf dem lokalen PC durchführen
  • Skript(e) testen
  • Skript(e) zurück ins Projektarchiv übertragen (commit) und die Änderungen/Neuerungen kurz kommentieren

Achtung: Eine Versionsverwaltung ist k e i n Ablageplatz für Sourcecode mit Fehlern! Vor einem Commit muss der neue/geänderte Code nach bestem Wissen und Gewissen geprüft werden. (Idealerweise nicht nur vom Autor selbst, sondern zusätzlich noch von einem anderen Programmierer.)



3.
Die Programmierung erfolgt mit folgenden Einstellungen in der php.ini:
  • error_reporting = E_ALL
  • register_globals = Off
  • safe_mode = Off


Über den Wert von safe_mode lässt sich ggf. streiten, da dieser abhängig vom System und dessen "Einsatzgebiet" ist. Im Intranet würde ich den safe_mode im Normalfall deaktivieren und bei Internet-System aktivieren.



Dateien und Verzeichnisse
Alle Datei- und Verzeichnisnamen sind grundsätzlich in Kleinschreibung einzubinden. Es werden keine Umlaute und Sonderzeichen (einzige Ausnahme: Unterstrich) bei der Vergabe von Datei- / Verzeichnisnamen genutzt.

gut  :  dbaccess.php, icon_ok.gif, kundenverwaltung.php
schlecht  :  DBaCCeSS.php, icon-ok.gif, kunden verwaltung.php




Namenskonventionen
1.
Konstanten sind groß zu schreiben:
  • define ('SORTAUFSTEIGEND', "ASC");
  • define ('LANG_BUTTON_YES', "Ja");



2.
Bei der Wahl des Namens für Variablen, Funktionen, Methoden, Klassen usw. ist der Programmierer (fast) frei in seiner Entscheidung. Ein Name sollte selbsterklärend und die Groß- und Kleinschreibung logisch gesetzt sein. Abkürzungen sind in Ausnahmefällen (Wenn sie sinnvoll sind!) erlaubt.

gut  :  getBenutzer, createDelnote, CheckFile, saveID
schlecht  :  GeTBen, credel, schäckfeil, speichereidentifikationsnummer




Quellcode / Programmierung allgemein
1.
Wem das manuelle Formatieren von Text zu mühsam ist, dem sei ein sogenannter "Code-Beautifier" empfohlen. Es gibt zwar frei nutzbare (=kostenlose) Tools, doch habe ich bis jetzt kein Programm gefunden, das wirklich gut ist.
Meiner Erfahrung nach ist lediglich Kauf-Software wie Polystyle flexibel genug und leicht zu handhaben. Die 15-20 Euro für so ein Tool sind gut angelegt.

Folgende Formatierungen und Konstrukte sind einzuhalten (bezogen auf PHP/HTML), damit die Lesbarkeit von Quellcode gegeben ist:

a) Kommentar-Zeilen beginnen mit //
Block-Kommentare /* */ sind nach Möglichkeit zu meiden. (Ausnahme: Am Skriptanfang)

Der Grund: Beim Debuggen kann es vorkommen, dass man in einem Skript mit vielen Zeilen komplette Bereiche auskommentieren möchte, um einen Fehler besser eingrenzen zu können.

Diese Kommentierung geschieht der Einfachheit halber mit einem Block-Kommentar, funktioniert aber nicht, wenn bereits Block-Kommentare genutzt werden, da ja das */ einen Block-Kommentar wieder aufhebt.


b) Klammern sind ohne Einrückung unter das Kommando bzw. den Namen der Funktion, Methode usw. zu setzen:


Die von den Klammern eingeschlossenen Anweisungen sind um drei Leerzeichen einzurücken. Die Verwendung von Tabulatoren ist nicht zulässig, da es zu Problemen bei unterschiedlich konfigurierten Editoren und verschiedenen Betriebssystemen kommen kann.
(Allerdings sollte der Text-Editor in der Lage sein, die TAB-Taste so zu konfigurieren, dass genau 3 Leerzeichen eingefügt werden.)

Einzeilige Anweisungen erhalten ebenfalls ein Klammer-Paar:


Einzeilige IF-Abfragen dürfen zwecks Übersicht in eine Zeile geschrieben werden; insbesondere, wenn es mehrere hintereinander sind, die einen Block bilden:


Die Verwendung eines SWITCH-Konstruktes ist ggf. in Betracht zu ziehen.


c) Mathematische Berechnungen sind zu klammern und mit Leerzeichen entsprechend zu trennen:

gut  :  $i = (3 * 5) + 17 + ($hundert / 10);
schlecht  :  $i = 3*5+17+$hundert/10;


Auch wenn es (mathematisch gesehen) nicht zwingend erforderlich ist, erhöht es für den Menschen deutlich die Lesbarkeit.


d) Längere Zeichenketten sind mehrzeilig aufzubauen:


Texte werden grundsätzlich in Sprachdateien (bzw. in einer Datenbank) als Konstanten gepflegt und nicht "hartkodiert" in den Quellcode oder Templates geschrieben.

Grund: Wird das zu programmierende System mehrsprachig, ist das Hinzufügen von neuen Sprachen unproblematisch.
Ausserdem ist die Wartung der Sprachvariablen deutlich einfacher, wenn sie alle an einem Ort (Datei oder Datenbank) zu finden sind und man nicht in hunderten von Skripten suchen muss.


e) Skript-Änderungen werden im Header der Quelldatei protokolliert:


Diese Protokollierung kann vernachlässigt werden, wenn ein Versionierungssystem genutzt wird und dort Updates entsprechend ausführlich kommentiert werden.

Nach Möglichkeit führt stets der "Ur-Autor" des jeweiligen Skriptes die Änderungen durch. Dies spart Zeit, da ein Programmierer, der das Skript nicht kennt, sich erst "einlesen" muss.

Nach der Änderung wird das Skript zusätzlich von einem anderen Autor geprüft, bevor es ins LIVE-System übertragen wird.



2.
Kommentare im Quellcode sind Pflicht. Hierbei sollte aber unbedingt darauf geachtet werden, dass keine Umlaute oder Sonderzeichen genutzt werden.

Grund: In der Web-Programmierung arbeitet man ggf. mit unterschiedlichen Betriebssystemen und leider kommt es immer noch häufig vor, dass Umlaute/Sonderzeichen nicht korrekt konvertiert werden. Zwar gibt es mittlerweile Möglichkeiten, kompatible Dateien zu erstellen (UTF-8), doch wenn man sich angewöhnt, Umlaute gleich als ae, oe, ue usw. zu schreiben, muss man auf spezielle Dateiformate und andere Vorgaben gar nicht erst achten.



3.
Daten, Funktionen und Darstellung sind strikt voneinander zu trennen. Dies bedeutet, dass der anzuzeigende HTML-Code beispielsweise aus Templates (Vorlagen) kommt und nicht im PHP-Skript generiert wird.

Dabei basiert der Trennungs-Gedanke auf der MVC-Architektur, die gerade bei Web-Systemen relativ einfach und unkompliziert umgesetzt werden kann. Hilfreich sind dabei Tools wie die PHP Template Engine Smarty




Datenbank
1.
Benutzereingaben werden niemals ungeprüft in die Datenbank geschrieben. Umlaute und Sonderzeichen sind durch den entsprechenden HTML-Code zu ersetzen und erst dann in der Datenbank zu speichern.

Grund: Bei Datenbank-Exports kann es vorkommen, dass bei unterschiedlichen Betriebssystemen Umlaute falsch übertragen werden und die Ziel-Datenbank fehlerhafte Einträge erhält.

Ich musste 2006 bei einer System-Portierung von Windows nach Linux mehrere 1000 Datensätze manuell nach Umlauten durchsuchen und ändern, weil die Programmierer damals keineswegs auf eine systemkompatible Datenspeicherung geachtet haben.
Seitdem beherzige ich diese Richtlinie ganz besonders.

Anmerkung: Eine als UTF8-kodierte Datenbank ist eine gute (bessere) Alternative, doch oft muss man auf bestehende Datenbanken arbeiten und dann ist es schwierig, nachträglich Änderungen der Zeichenkodierung vorzunehmen.


2.
Die Namen von Datenbank-Tabellen und -Feldern bestehen aus Kleinbuchstaben. Umlaute und Sonderzeichen (Ausnahme: Unterstrich) sind nicht erlaubt.


3.
Jede Tabelle besitzt ein Feld "id" zur eindeutigen Identifikation eines Datensatzes: INT(11), auto_increment, Primärschlüssel
(Dies ist selbstverständlich nur als "Regelfall-Vorgabe" zu betrachten. Es gibt auch Tabellen, bei denen der Primärschlüssel durch ein anderes Feld sinnvoll abgebildet werden kann bzw. ein Primärschlüssel aus der Kombination mehrerer Felder besteht.)


4.
Die Datenbank-Zugangsdaten sind in einer zentralen Datei zu speichern, die bei jedem Seitenaufruf eingebunden wird. Bei einem entsprechend großen System empfehle ich die Verwendung eines Datenbank-Moduls, wie bspw. die MDB2.

Wird das System ggf. auch für andere DBMS (MySQL, MS-SQL,...) programmiert, empfiehlt es sich, eine zentrale Datenbank-Datei mit allen SQL-Anweisungen zu nutzen. Bei der Konvertierung bzw. Anpassung muss damit nur eine Datei "angefasst" werden.


5.
Sensible Daten werden niemals im Klartext in die Datenbank geschrieben. Bei Passworten ist ein HASH-Wert (MD5, SHA1, etc.) akzeptabel; besser wäre jedoch eine Verschlüsselung. Bei sensiblen Daten ist eine Verschlüsselung (bspw. AES) Pflicht.
Dadurch hätte ein Angreifer mit dem Diebstahl der Datenbank nichts gewonnen, sondern bräuchte zur Entschlüsselung noch zusätzliche Informationen über die Art der Verschlüsselung bzw. das Passwort, das er nur im Quellcode findet. (Wenn der Angreifer auch Zugriff auf das Dateisystem hat, bringt die Verschlüsselung natürlich gar nichts, doch dann sind Hopfen und Malz sowieso verloren und irgendwas ist bei der Sicherung des Servers ganz mächtig schief gelaufen.)


Sonstiges
Texte, die Informationen für Programmierer oder Administratoren enthalten, sind "versionierungssicher" als einfache Text-Datei (ASCII/ANSI) in einem separaten Projektarchiv (Repository) zu speichern.

Wie bei den Kommentaren im Quellcode sind Umlaute als ae, ue, oe usw. zu schreiben. Auf die Verwendung von Sonderzeichen sollte verzichtet werden. Im Zweifelsfall ist das Sonderzeichen auszuschreiben: EURO, PARAGRAPH usw.