PHP-Code strukturiert und dokumentiert
Sauberer Code
Teamarbeit
PHP-Code strukturiert und dokumentiert
Ob ein PHP-Programm funktioniert oder nicht, ist nur ein Kriterium für den Erfolg eines Programmierers. Auch wie das Ergebnis zustande gekommen ist und wie es sich einem dritten Betrachter präsentiert, ist von entscheidender Bedeutung. Die gilt vor allem für professionelle Applikationen und insbesondere auch für Open-Source-Projekte. Gerade hier geht es ja darum, dass die Community sich dieses Projekts annimmt und es gemeinsam weiterentwickelt und pflegt.
Auch kommerzielle PHP-Applikationen sind selten das Ergebnis eines engagierten Einzelkämpfers, sondern sie werden von Programmierteams gemeinsam entwickelt. Eine solche Arbeitsweise setzt jedoch voraus, dass Dritte den Code jederzeit verstehen und dort nahtlos weitermachen können, wo ein anderes Mitglied des Teams aufgehört hat. Damit ein solches Teamwork funktioniert, muss ein professioneller Programmierstil gepflegt werden. Verständlich, dass eine solche Anforderung der Todfeind jeglichen Individualismus beim Codieren ist.
Aber auch Einzelkämpfer sollten die berüchtigte, nur am Funktionalen interessierte Spaghetti-Methode beim PHP-Codieren tunlichst vermeiden. Selbst wenn ein so zusammengeschustertes Skript funktioniert, rächt sich dieser Programmierstil bitter, wenn es nach einiger Zeit ans Modifizieren oder Erweitern des Programms geht. Vielfach kennt sich ein Programmierer in solchen Situationen dann in seinem eigenen Code nicht mehr aus, und eine mühsame Neuprogrammierung oder ein dramatischer Anstieg von Errors sind die Folgen.
Bleibt die Frage, was ein sauberer Programmierstil in PHP ist. Eine reine Lehre, die ohne jeden Zweifel allgemein anerkannt ist, gibt es nicht, jedoch eine Menge Ansätze. Zum Beispiel gibt es für Beiträge zu Pear, dem PHP Extension and Application Repository, die Coding-Standards, ohne die nichts läuft. Hier werden bis ins Detail Einrückungen, Zeilenlängen, Namenskonventionen, Dateiformate und der Zwang zum Kommentieren des Codes festgelegt. Wer sich auf den Weg zu einem sauberen Programmierstil macht, kann die dort festgelegten Definitionen als hilfreiche Wegmarken zur Kenntnis nehmen.
Schwierig wird die Sache dadurch, dass PHP sehr kulant und nachsichtig ist, wenn es um funktionierenden Quellcode geht. Das heißt, ein PHP-Skript hat auch dann gute Chancen, zu funktionieren, wenn man sich um einen guten Stil keinen Deut schert. Allerdings sollte man die Toleranz von PHP nicht unbedingt bis zum äußersten ausreizen und sich um einen guten Stil bemühen. Die Beachtung der folgenden Regeln und Prinzipien kann dabei hilfreich sein.
Typisierung
PHP-Code strukturiert und dokumentiert
Ein großer Unterschied zwischen PHP und einer modernen Programmiersprache wie zum Beispiel C oder Java liegt in der Typisierung von Variablen. Damit ist gemeint, dass eine Variable beispielsweise als Integer definiert wird und fortan nur noch ganzzahlige positive oder negative Werte annehmen kann. Dementsprechend gibt es Typen unter anderem für Strings (Zeichenketten), Char (Zeichen), Float (Fließkommazahlen) und Boolean (true/false). Der Typ einer Variablen lässt sich im Nachhinein jedoch nicht mehr verändern, lediglich der Wert kann in einen passenden Typ konvertiert werden.
Typisierung bringt große Vorteile mit sich: Der Quellcode ist wesentlich übersichtlicher und besser lesbar, da man immer weiß, von welchem Typ der zugewiesene Wert einer Variablen ist und zugewiesen werden kann. Zusätzlich ergibt sich daraus ein wesentlich stabilerer Code. Das Fehlen einer solchen Typisierung bei PHP bringt nun einige Probleme mit sich, die sich durch einen guten Programmierstil jedoch umgehen lassen.
Um Abhilfe zu schaffen, gibt es eine Konvention, bei der dem Bezeichner einer Variablen eine Zeichenfolge vorangesetzt wird, die den Typ der Variablen beschreibt. Für Integer-Werte wird in der Regel int und für Boolean bool verwendet. Aus $p wäre also $intP sowie $boolP geworden. Da dies zwei unterschiedliche Variablen sind, wäre es zu keiner Kollision gekommen. Allgemein wird diese Methode als »ungarische Notation« bezeichnet. Dabei gelten folgende Vereinbarungen: Für String-Variablen str, für Integer-Variabeln int, für Fließkomma-Variablen f oder flt, für Boolesche-Variabeln b oder bool, für Array a oder arr, für Objekte obj und für Klassen c oder class.
Die Vorteile einer solchen Konvention liegen auf der Hand: Zum einen reduzieren die Prefixe die Fehlerquote, zum anderen wird der Code dadurch insgesamt verständlicher und für Dritte besser nachvollziehbar.
Namen für Variablen, Funktionen und Klassen
PHP-Code strukturiert und dokumentiert
Aber nicht nur die Verwendung solcher Kennzeichnungen ist eine Erfordernis modernen Programmierstils. Auch die Wahl der Namen von Variablen, Funktionen und Klassen muss klaren Vorgaben folgen.
Durch eine vernünftige Benennung von Klassen, Funktionen und Variablen erreichen Sie eine deutlich höhere Lesbarkeit und Verständlichkeit Ihres Codes. Ein Beispiel:
Das Programm funktioniert einwandfrei. Was aber, wenn Sie wirklich 1000 Zeilen Code zwischen der Zuweisung des Wertes und der Ausgabe der Variable haben? Dann wissen Sie nicht mehr, welche Ausgabe Sie von $a zu erwarten haben.
Noch schlimmer wird es, wenn Variablenzuweisung und Ausgabe über mehrere Include-Dateien verteilt sind und Sie an einer komplexen Website mit vielen Ausgabezeilen arbeiten. Besser ist es, die Variablennamen so zu wählen, dass sie etwas über sich selbst aussagen, zum Beispiel:
Hier wissen Sie auch noch 1000 Zeilen später, dass es sich um eine Variable handelt, die eine Zeichenkette (string) beinhaltet und zur Begrüßung dient. Natürlich können Sie auch deutschsprachige Bezeichnungen wählen, also $strBegruessung; Vorsicht nur mit Umlauten in Variablennamen. Die funktionieren zwar. Doch kann es zu Problemen kommen, falls der Quellcode einmal von einer anderen Plattform aus bearbeitet wird. Da kann es vorkommen, dass statt der Umlaute nur kryptische Sonderzeichen erscheinen.
Es spricht einiges dafür, sich bei Namen auf englische Bezeichnungen zu stützen. Gerade bei der Web-Affinität von PHP ist zum Beispiel bei einer Open-Source-Applikation, die Sie ins Netz stellen, ein internationales Publikum gewährleistet. Sie können die Arbeit Ihrer internationalen Kollegen, die das Skript nutzen, anpassen und etwa erweitern wollen, dadurch wesentlich vereinfachen.
Meist bestehen Namen von Variablen oder Funktionen aus mehreren Wörtern. Schreiben Sie diese Wörter zusammen und beginnen Sie jedes Wort groß, zum Beispiel:
function getObjectData()
Ob Sie den ersten Buchstaben groß oder klein schreiben, bleibt Ihnen überlassen. Übrigens achtet PHP selbst nicht auf die Groß- und Kleinschreibung.
Gute Namen finden
PHP-Code strukturiert und dokumentiert
Nun gilt es nur noch, geeignete Namen für die Variablen und Funktionen zu finden. Selbst definierte PHP-Klassen und die daraus entstehende Objekte sollten Sie grundsätzlich mit Substantiven benennen und bei der Codierung nach folgendem Muster vorgehen:
class classText
oder
$objText = new classText();
Methoden oder Funktionen lassen sich meist mit einem Verb gut beschreiben, zum Beispiel:
function readText()
Aber Achtung: In dieses Beispiel ist schon eine Falle eingebaut: Was bedeutet read? Heißt das, die Funktion liest einen Text ein, oder bedeutet es, dass der Betrachter der Seite einen Text ansehen darf? Im Normalfall tippt man auf die erste Variante. Aber der Eindeutigkeit halber könnte man die Funktion
function readTextFromDb()
nennen. Wenn Sie eine Methode benennen, können Sie in diesem Beispiel auf das Text verzichten. Denn das Objekt deutet ja schon an, dass es um Text geht, also nehmen Sie:
$objText->readFromDb();
Namen von Variablen und Eigenschaften sind meist auch Substantive.
Verwendete Sprache
PHP-Code strukturiert und dokumentiert
Eng mit der Namensfindung für Variablen, Funktionen und Klassen hängt auch das Problem der Lokalisierung einer Applikation zusammen. Vermeiden Sie unbedingt, Hinweise, Formularbeschriftungen, Buttons und andere Elemente der Bedienoberfläche in einer Sprache
»hart« in den jeweiligen Skripts zu codieren. Bedauerlicherweise wird diese Methode bei einem Großteil der frei im Netz verfügbaren PHP-Applikationen angewandt, und zwar in der englischen Variante. Eine Lokalisierung in eine andere Sprache wird dadurch ein sehr aufwendiges Unterfangen und vielfach unmöglich. Besser ist es, hier mit Variablen zu arbeiten und alle Werte dieser Variablen in ein Lokalisierungs-File auszulagern. Von modernen PHP-Applikationen wird dieses Verfahren immer praktiziert.
Konstanten definieren
PHP-Code strukturiert und dokumentiert
Eine Konstante bezeichnet einen Wert, der mittels eines Bezeichners gelesen, aber nicht verändert werden kann. Häufig wird in einem PHP-Skript dazu eine normale Variable verwendet. Dies ist prinzipiell in Ordnung, da der Wert nun nur noch einmal im Skript zugewiesen werden muss – jedoch kann der Wert aus Versehen überschrieben und somit geändert werden. Mit define können Sie eine Konstante definieren. Konstanten fangen nicht mit einem $-Zeichen an und werden in Großbuchstaben geschrieben. Konstanten stehen überall und zu jeder Zeit zur Verfügung.
Redundanten Code vermeiden
PHP-Code strukturiert und dokumentiert
Je mehr Skripts Sie schreiben und je länger diese werden, desto häufiger werden Sie auf sich wiederholende Codezeilen stoßen. Grundsätzlich sollten Sie diese Fragmente in Funktionen oder Klassen auslagern. Denn wenn die Codefragmente immer die gleiche Aufgabe erledigen sollen, kann das bei einer einzelnen Änderung in Sucharien ausarten. Außerdem können sich hier sehr leicht Programmfehler einschleichen, wenn man eine Passage beim Patchen übersieht.
Funktionen, die beispielsweise logisch zusammengehören, weil sie bestimmte Zeichenkettenoperationen durchführen, lassen sich auch gut in einer Bibliothek unterbringen. Letztere ist einfach nur ein PHP-Skript, in welchem die Funktionen definiert wurden und das dann mittels include in ein gerade benötigtes Projekt eingebunden werden kann.
Die Kommentare
PHP-Code strukturiert und dokumentiert
In PHP gibt es zwei Arten von Kommentaren: Einzeilige Kommentare beginnen mit einem doppelten Schrägstrich, zum Beispiel:
// ID-Nummer des Beitrags
Die andere Variante sind mehrzeilige Kommentare. Sie beginnen mit /* und enden mit */, also:
/*
Das ist ein Kommentar, der sich
über mehrere Zeilen erstreckt.
*/
Der einzeilige Kommentar passt auch hervorragend hinter den Quellcode, zum Beispiel:
$intCounter = 0; // Datensatzzähler
Wenn Sie die Regeln zur Benennung von Variablen und Funktionen beachten, ist ein wesentlicher Teil der Dokumentationsarbeit bereits erledigt. Denn gut lesbarer Code erklärt sich fast von selbst. In den Kommentaren müssen Sie also nicht mehr unbedingt notieren, wie etwas funktioniert. Sie können sich im Quelltext weitgehend auf Kommentare beschränken, die sagen, warum Sie etwas gemacht haben.
Außerdem ist es sinnvoll, jeder Funktion oder Methode einen Kommentar mitzugeben. Der beschreibt die Funktion und zeigt, welche Parameter sie verlangt. Zusätzlich ist eine Auskunft über den Rückgabewert sinnvoll. Das gilt auch für Klassen und deren Methoden. Innerhalb von Funktionen sollten Sie Kommentare möglichst sparsam verwenden. Sonst wird der Code zu unübersichtlich. Hier eignen sich die Einzeiler hinter dem Code am besten. So bleiben der Quelltext und dessen Struktur lesbar.
Schließlich sollte auch jede PHP-Datei am Anfang einen Kommentar enthalten. Dieser erklärt, was die Datei macht, zu welchem Projekt sie gehört und wer sie wann programmiert hat.
Bei den Kommentaren an sich gilt: knapp und verständlich halten. Schreiben Sie keine Romane, weshalb und wie genau Sie die Funktion programmiert haben. Bedenken Sie immer, dass möglicherweise auch andere die Dokumentation einmal lesen und schnell verstehen wollen. Falls Sie überlegen, Ihr Skript im Internet zum Download freizugeben, schreiben Sie die Kommentare am besten gleich auf Englisch.
Vermeiden sollten Sie jede Art von Flapsigkeit – auch wenn es witzig sein sollte. Denn möglicherweise liest irgendwann ein anderer den Quellcode. Da wirkt der vermeintliche Scherz nur noch peinlich.
Nach Möglichkeit sollten Sie sich auch mit Selbstkritik und To-do-Listen innerhalb des Quelltextes zurückhalten. Solche Kommentare sind während der Entwicklungsphase noch in Ordnung, sollten dann aber gestrichen werden, wenn Sie fertig sind. Denn solche Kommentare bringen andere Leser auf den Gedanken, dass Ihre Software nicht ausgereift ist und dass Sie selbst nicht zu Ihrem Werk stehen.
Etwas Kosmetik
PHP-Code strukturiert und dokumentiert
In den Coding-Standards von Pear gibt es genaue Anweisungen über Einrückungen (vier Blanks, keine Tabs) und Zeilenlängen. Ob man diese peniblen Vorgaben eins zu eins in seinen Programmierstil übernehmen will, sei dahingestellt. Dass eine Strukturierung des Quellcodes durch Einrückungen, Zeilenumbrüche und Leezeilen die Lesbarkeit erhöht, ist jedoch unbestritten. Nur so kann ein Programmierer, der sich eines solchen PHP-Skripts annehmen will, schnell erkennen, was sich in einer Schleife oder einer Kontrollstruktur konkret abspielt. Auch der Einsatz von Blanks zur besseren Kennzeichnung von Zuordnungen (=) kann die Lesbarkeit ebenso erhöhen wie deren vertikaler Anordnung untereinander bei mehreren Zuweisungen. Das kann dann zum Beispiel so aussehen:
$l = foo($bar);
$lo_variable = foo($baz);
$lon_variable = foo($baz);
$long_variable = foo($baz);
Auch die Definition eines Arrays kann man mit entsprechenden Einrückungen gut strukturieren:
$a = array('Farbe' => 'rot', 'Geschmack' => 'süß', 'Form' => 'rund', 'Name' => 'Apfel', );
Bleibt noch die Frage, ob die ganze Kosmetik eines gut lesbaren Quellcodes nicht der Performance schadet. Minimal: PHP überspringt alle Kommentare und überflüssigen Leerzeichen wie zum Beispiel Einrückungsleerzeichen bereits beim Parsen des Programms. Das geht selbst bei extrem umfangreichen Kommentaren vernachlässigbar schnell. Zur Performance-Steigerung gibt es jedenfalls bessere Methoden als der Verzicht auf einen gut lesbaren und strukturierten Quelltext.