php Coding Standard
Der php Coding Standard stellt eine Struktur da, der immer gefolgt werden sollte.
Wenn man dem Extreme Programming folgt, wird man wissen, dass die Einhaltung eines Coding Standards ein wichtiger Bestandteil der gesamten Projektarbeit ist. Darüber hinaus gibt es jedoch auch andere wichtige Faktoren:
- Kommunikation
- Urlaubsvertretung
- funktionierender Code
- übersichtlicher Code
- Module und Modultests
- Wiederverwendbarkeit des Codes
- einfache Wartung des Codes
- Code, der leicht zu erweitern ist
- Unterstützung von Refactoring
um nur einige zu nennen. Bis auf den Punkt "Kommunikation" unterstützt ein Coding Standard alle genannten Punkte. Selbst die Urlaubsvertretung wird einfacher, denn wenn jeder den Code des anderen versteht, kann man auch schnell Bug-Fixes vornehmen oder Module des anderen verwenden ohne das Rad neu zu erfinden.
Um diese Ziele zu erreichen, muss eine PHP-Applikation
- leicht zu lesen
- leicht verständlich
- gut dokumentiert
- durch verschiedene Programmierer wartbar
- frei von typischen Fehlern
sein. Im besten Falle kann sogar ein Kunde die Module der PHP-Applikation verstehen und weiter verwenden.
Das Ziel von leicht verständlichem Source-Code ist erreicht, wenn jedes Mitglied des Teams, jedes Modul aus dem Stehgreif erklären kann.
Es folgen die Regeln, die eingehalten werden sollten. Im Gegensatz dazu stehen die Empfehlungen, denen man nicht folgen muss. Die Beispiele in Richtig und Falsch sollen die Regeln und Empfehlungen verdeutlichen.
Immer wenn eine Regel gebrochen wird, muss das deutlich und erkennbar dokumentiert werden
Dies ist die wichtigste Regel, denn sie erlaubt zum einen Freiheit und erfordert zum anderen genaue Dokumentation, warum man sich für einen Bruch der Regeln entschieden hat. Auch beim Brechen von Regeln sollte das Prinzip der Einfachheit weiter angewendet werden.
Beispiel:
Sie wollen zwei Variablen miteinander vergleichen und das Ergebnis "$boolean" zuweisen. Die erste Variante ist die einfachste, aber es gibt mehrere Möglichkeiten das zu programmieren:
Das Beispiel zeigt kurze und ausführliche Programmierung. In jedem Fall wird mit "var_dump($boolean);" der Wert "bool(true)" ausgegeben. Das dritte Beispiel ist nach dem PHP Coding Standard ungültig, weil die geschweiften Klammern fehlen. Würde das Fehlen und der Grund genau dokumentiert werden, hätte man Regel 0 beachtet. In dem hier dargestellten Fall sollte man nach dem Prinzip der Einfachheit die erste Variante wählen.
Das Prinzip der Einfachheit: Don't make me think!
Das Prinzip der Einfachheit besagt: "Don't make me think!" Sinngemäß übersetzt heißt das: "Bringe mich nicht zum Nachdenken!"
Wenn man also eine lange und komplizierte Funktion durch eine Klasse mit vier oder fünf übersichtlichen Methoden ersetzen kann, so ist der Aufwand nahezu immer gerechtfertigt. Kann man komplexe und unstrukturierte iterative Programmierung durch eine elegante Rekursion ersetzen, sollte man diese Arbeit nicht scheuen.
Das Prinzip der Einfachheit findet man überall im Leben, aber in der Programmierung wird es nur selten angewendet. Hier ist das Hauptprinzip: "Hauptsache es läuft!". Es sollte jedoch das Prinzip der Einfachheit sein. Code sollte modular, wartbar und wiederverwendbar sein.
Zum Prinzip der Einfachheit gehören automatisch Struktur und Übersichtlichkeit. Der PHP Coding Standard wird hier verschiedene Mechanismen erklären, um das zu erreichen. Der weltweit wichtigste und weitverbreiteste Standard ist das Einrücken von Code.
Die vielen Beispiele in diesem Dokument werden das Einrücken von Code besser erklären, als jede abstrakte Formel.
Dateien, die inkludiert werden sollten, mit "*.inc.php" benennen.
Es ist besser ein Unterverzeichnis ("include" oder "inc") für die Dateien anzulegen, die per include() oder ähnlichen Befehlen inkludiert werden. Oft werden hier Verzeichnisse wie "lib" oder "class" verwendet. Das widerspricht jedoch dem Prinzip der Einfachheit, weil der Name "include" für jeden PHP-Programmierer eine eindeutige Verbindung zum gleichnamigen PHP-Befehl herstellt. Das INCLUDE-Verzeichnis kann auch für CSS- und JavaScript-Dateien verwendet werden. Empfohlen wird jedoch ein eigenes Unterverzeichnis.
Möchte man, aus welchen Gründen auch immer, alle INCLUDE-Dateien im Hauptpfad ablegen, so muss die Dateiendung "*.inc.php" verwendet werden. "*.inc" reicht nicht aus, weil diese Dateiendung standardmäßig nicht geparst wird und demnach alle Informationen der Datei im Klartext vorliegen.
Jede PHP-Datei muss das Copyright und einen Kommentar enthalten, der die Funktionalität beschreibt.
Der C++ Coding Standard geht davon aus, dass in jeder Datei mit Source Code auch der Dateiname erwähnt wird. Dieses Konzept erscheint mir unlogisch, weil der Dateiname beim Bearbeiten und Drucken bekannt sein sollte. Trotzdem steht es jedem Entwickler frei, den Dateinamen mit in den Kopf einer Datei aufzunehmen.
Das Copyright sollte zur Wahrung der eigenen Rechte oder der gewählten Lizenz in jeder PHP-Datei erwähnt werden. Wurde das Produkt über mehrere Jahre entwickelt, dann sollte jedes Jahr erwähnt werden.
Wenn viele Autoren an einem Projekt arbeiten und auch noch verschiedene Lizenzen im Spiel sind (wie bei PEAR) ist es unter Umständen sinnvoll, folgende Version zu verwenden:
Die Sprache für Kommentare und Bezeichner sollte Englisch sein.
Bezeichner von Variablen, Funktionen, Klassen und so weiter sollten in Englisch definiert werden. Alle Kommentare und Dokumentation sollte ebenfalls in Englisch erfolgen.
Es ist absolut notwendig und unumgänglich Source-Code zu dokumentieren. Wenn keine zwingenden Gründe dagegen sprechen, sollten als Projektsprache Englisch genommen werden, um Personen aus anderen Ländern einen möglichst einfachen Zugang zum Projekt zu gewähren.
Unbedingt zu vermeiden ist eine Mischung der englischen und der deutschen Sprache, gerade wenn es um die Benennung von Variablen geht.
Ein Team entscheidet sich dazu, Deutsch als Projektsprache zu nehmen. Damit entsteht nahezu automatisch das Problem der Sprachmischungen:
Wie man unschwer sehen kann, muss man in einer deutschen Sprachumgebung auf Variablen wie
- $result
- $select
- $query
- $row
verzichten und sich geeignete Äquivalente ausdenken.
Jede Datei wird mit Änderungskommentaren und einem Zeitstempel versehen.
Wenn kein SVN oder CVS zur Verfügung steht, sollte das Team eine Konvention vereinbaren, wie es Änderungen am Source-Code dokumentiert. Zum Beispiel könnte man die Initialen jedes Teammitglieds verwenden plus das Datum.
Es wird empfohlen fünf dieser Kommentare aufzubewahren, damit die letzten (Arbeits)Schritte nachvollzogen werden können. Ob die Kommentare im Kopf der Datei gemacht werden oder an der Stelle, wo die änderungen gemacht werden, sollte das Team vor dem Projekt entscheiden und dann einheitlich für alle Dateien umsetzen.
Jede Funktion muss mit Kommentaren versehen werden.
Eine der wichtigsten Aufgaben der Programmierung liegt in der Dokumentation der Funktionen bzw. Methoden. Das ist in einem Team unverzichtbar, denn so können die anderen Team-Mitglieder alle Funktionen verstehen, verbessern und nutzen.
Funktionen, Parameter und Rückgabewerte müssen sauber dokumentiert sein.
Pro Zeile die Erklärung für einen Parameter. Diese Zeile sollte nach Möglichkeit alles über den Parameter aussagen. Extreme Programming hat zum Ziel, einen möglichst hohen Qualitätsstandard zu setzen. Diese Funktion zeigt sehr gut, wie das erreicht werden kann und wie eine Funktion dokumentiert sein sollte. Wichtig sind die Datentypen ("string", "boolean"), die Namen aller Parameter ("$host", "$user", "$password", "$database"), eine Beschreibung und ein Beispiel. Die Angabe des Wertebereichs ist optionial.
Der Wertebereich bietet sich vor allem bei Integer-Parametern an, weil diese manchmal nur positiv verwendet werden, obwohl negative Werte auch denkbar sind. Dieses sollte aus einem Kommentar auf jeden Fall hervorgehen.
/
Beispiel: "@param integer $total_entries: total entries in table 'users' (range: 1 to 65536), e.g. '257', '5864' or other unsigned values"
Oder man gibt den den Datentypen aus MySQL an, wie TINYINT oder BIGINT. Sind negative Werte auch möglich, sollte auf jeden Fall ein Wertebereich angegeben werden und das Beispiel sollte eine negative und eine positive Zahl enthalten. Wie schon gesagt, die Zeile sollte nach Möglichkeit alles über den Parameter aussagen.
Lange Kommentare mit /* und kurze mit //.
Das PEAR-Projekt dokumentiert sehr ausführlich auch einzelne Variablen:
Man kann sich sehr leicht vorstellen, dass eine solche Verfahrensweise sehr viel Arbeit macht und es für jede Zeile auch übertrieben wäre. Systemkritische Variablen und Konstanten sollten aber auf diese Art und Weise dokumentiert werden.
Denken Sie bei Kommentaren an die lesende Zielgruppe, aber ein wenig Fachwissen kann ruhig vorausgesetzt werden. Wenn also die Zeile
$boolean = ($i > $j);
in Ihrem Team jeder versteht, lassen Sie den Kommentar weg.
Der C++ Coding Standard spricht von strategischen oder taktischen Kommentaren.
Ein strategischer Kommentar beschreibt eine Funktion oder einen ganzen Absatz des Source-Codes. Ein strategischer Kommentar wird vor dem Code plaziert.
Ein taktischer Kommentar beschreibt eine bestimmte Zeile und wird - wenn möglich - ans Ende der Zeile (also hinter dem Code) plaziert. Auch wenn der Kommentar ohne den Code nicht sinnvoll ist, sollte man einen taktischen Kommentar verwenden.
Alle Bezeichner werden aussagekräftig und eindeutig definiert.
In einem Programm können viele Bezeichner/Namen definiert werden. Jede Variable (Funktion, Konstante, etc.) braucht einen Bezeichner. Diese Bezeichner müssen aussagekräftig und eindeutig definiert werden. Sie sollten nicht zu lang sein, aber auch nicht so kurz, dass die Bedeutung der Variable unklar ist.
In jedem (guten) Programmierkurs lernen Sie sprechende Variablen zu verwenden. Sprechende Variablen sagen etwas über den Inhalt und die Verwendung aus. Bezeichner aussagekräftig zu definieren ist dafür eine globale Umschreibung.
Beispiel: Sie programmieren Auswertungen (englisch: reports) über den Zugriff auf einen Bankautomat. Dazu benutzen Sie in Ihrer Funktion die PHP-Funktionen mysql_query und mysql_num_rows. Sie könnten die Funktion "rep_mq_mnr()" nennen. Das steht für "report_mysql_query_mysql_num_rows". Ein sehr schlechter Name für die Funktion.
- Keine Abkürzungen verwenden, die niemand kennt.
- Beide Versionen des Namens sagen nichts über die Funktionalität, den Sinn und Zweck und die Arbeitsweise der Funktion aus.
Erzeugt die Funktion Grafiken? Dann wäre der Name "create_graphics()" sinnvoll. Oder das Ergebnis von "mysql_num_rows()" enthält alle Bankautomat-Logins des heutigen Tages, dann wäre "check_all_logins_for_today()" oder auch "get_logins_today()" eine gültige Bezeichnung. Die zweite Variante könnte schon wieder unklar sein, denn die Übersetzung könnte auch lauten: "Hole dir heute die Logins."
Einen Namen eindeutig zu vergeben bedeutet zum Beispiel:
- Zwei Variablen nicht nur durch Groß- und Kleinschreibung zu unterscheiden, also nicht Variable A "$result" und Variable B "$Result".
- Variablen nicht durchnummerieren, also nicht "$var1", "$var2", etc.
- Zahlen in Namen vermeiden, also eine Konstante nicht in einem Skript mit "I0" (I + Ziffer "0") und dann im nächsten mit "IO" (I + Buchstabe "O") definieren.
Benennung von Variablen und Funktionen erfolgen mit Unterstrich und in Kleinbuchstaben.
Wie schon erwähnt ist der Einsatz von Abkürzungen mit Vorsicht zu genießen. Es kann begründete Fälle geben, wo es sinnvoll ist, eine Abkürzung zu verwenden, aber die Regel "Benennung von Variablen und Funktionen erfolgen mit Unterstrich und in Kleinbuchstaben" soll den Einsatz von Abkürzungen zusätzlich erschweren.
Wenn jeder im Team die Abkürzung RDBMS kennt, dann kann man sie auch verwenden. Um den Einsatz von Abkürzungen zu ermÖglichen und Variablen eindeutig und mit mehreren Worten benennen zu können, benutzt man den Unterstrich zur Trennung der Wörter:
Kleinbuchstaben erleichtern die Suche nach Variablen. Einige Editoren und die meisten Linux-Systeme unterscheiden zwischen Groß- und Kleinschreibung. Sie arbeiten case-sensitive.
Konstanten werden in Großbuchstaben defniert.
Für Konstanten gelten die gleichen Regeln wie für andere Bezeichner.
Eine Ausnahme gibt es jedoch: Alle Konstanten werden groß geschrieben, so wie es bei php.net (Konstanten) auch vorgeschlagen wird. Gute Bezeichner für Konstanten sind:
- START_VALUE
- DATABASE_PREFIX
- ENCRYPTION
und so weiter.
Das Beispiel zeigt den richtigen Gebrauch Konstanten. Viele Konfigurationsdateien verwenden Variablen. Allerdings ändert sich die Konfiguration für ein RDBMS nicht im laufenden Betrieb, also sollten auch keine Variablen verwendet werden. Konstanten sind hier die bessere Wahl.
Einndeutige Abkürzungen verwenden.
Stellen Sie sich vor, Sie finden in einem PHP-Skript die Variable "$back". Man könnte jetzt annehmen, dass diese Variable etwas mit "Zurück" zu tun hat. Mir ist allerdings ein Fall bekannt, wo "back" eine AbkÜrzung für "Backend" war. Im gleichen Projekt wurde auch die Abkürzung "lan" für "language" verwendet. "LAN" ist jedoch (weltweit) eine Abkürzung für "Local Area Network".
Wenn auch nur ein Mitglied im Team über so etwas "stolpert", geht wertvolle Zeit verloren. Das muss unter allen Umständen vermieden werden. Das man "back" schneller getippt hat als "backend" ist natürlich wahr, aber aus solcher Faulheit - und wir reden hier von vielleicht zwei Sekunden Mehraufwand - können sich fatale Folgen ergeben:
- Ein Team-Mitglied versucht mehrere Stunden herauszubekommen, warum in den Tabellen, die mit "lan" beginnen, keine Spalten vorhanden sind, die Informationen über Netzwerke (LAN) oder IP-Adressen enthalten.
- Eine Person denkt darüber nach ein AddOn oder Plugin für eine GPL-Software zu schreiben. Aufgrund der schlechten Strukturen in der Datenbank und im Source-Code entscheidet er sich jedoch dagegen und macht sich auf die Suche nach einem anderen, vergleichbaren GPL-Produkt.
- In einer Besprechung wird ein Bug in der Software entdeckt. Aufgrund von fehlender Dokumentation und vielen Abkürzungen, die selbst von den Programmierern nicht mehr entschlüsselt werden können, wird die Suche nach dem Bug deutlich erschwert.
Um solche Probleme zu umgehen sollten Sie folgendes beachten:
- verwenden Sie so wenig Abkürzungen wie möglich
- nur Abkürzungen benutzen, die jeder im Team kennt
- auf keinen Fall Abkürzungen verwenden, die zweideutig sein können
Abkürzungen wie "RDBMS" können schnell über Google gefunden werden und sind den meisten Personen in der EDV bekannt. Sie können deswegen mit Vorsicht eingesetzt werden. Warum mit Vorsicht? Die Pflicht zur Kleinschreibung macht es noch schwieriger Abkürzungen zu erkennen und richtig zu deuten. Abkürzungen wie "cp" für "copy" dürfen niemals verwendet werden, weil der Aufwand vier anstatt zwei Zeichen zu tippen nahezu identisch ist.
Nehmen wir an, Sie haben die Möglichkeit eine Variable "$terminal_process" oder "$tp" zu nennen. Sie sollten immer die ausführliche Variante wählen, weil Sie mit
- Suchen & Ersetzen oder mit
- Copy & Paste
solche Variablen nicht immer wieder tippen müssen.
"$x" wird bei mathematischen Programmen und Funktionen verwendet. Das sollte allerdings nur gemacht werden, wenn alle im Team mathematische Kenntnisse haben. Der Variablenname "$extract_a_root" ("to extract a root" = "eine Wurzel ziehen") ist zwar nicht so kurz, aber viel sprechender als "$x". Der Bezeichner "$root" wäre hier wieder verwirrend, weil die Variable auch etwas mit dem Root-Account unter Linux zu tun haben könnte.
Einige Programmierer benutzen Variablen wie "$blnResult" oder "$strName", um den Typ einer Variable zu kennzeichnen. Das ist keine gute Idee, weil einige dieser Abkürzungen einem Programmierneuling nicht bekannt sind und selbst Google und das Wikipedia dazu keine direkten Treffer liefern. "str" ist unter anderem eine Abkürzung für "Straße" oder den Flughafen von Stuttgart. "bln" liefert noch verwirrendere Ergebnisse. Trotzdem werden Abkürzungen sehr häufig von Programmierern verwendet.
Funktionen, Parameter und Rückgabewerte dokumentieren.
Funktionen sollten immer einen Rückgabewert (Return-Parameter) haben. Falls Ihre Funktion ausschließlich zur Verarbeitung oder zur Ausgabe gedacht ist, sollte die Funktion trotzdem TRUE oder FALSE zurückliefern. Dieses ist dann ein Indikator dafür, ob die Funktion erfolgreich oder nicht erfolgreich gearbeitet hat.
Wie schon erwähnt müssen Funktionen, Parameter und Rückgabewerte sauber dokumentiert werden. Das gilt auch für die Rückgabewerte. Bezeichner und Parameter müssen "sprechend" und aussagekräftig sein.
Funktionsname:
Der Name/Bezeichner einer Funktionen sollte nach Möglichkeit ein Verb enthalten und genau beschreiben, was die Funktion macht. Ein Bezeichner sollte eher zu lang sein, als zu kurz. Aber "print_login_status_for_a_given_user()" würde zu weit gehen. Die Funktion sollte besser "print_user_login_status()" oder nur "print_login_status()" heißen.
Parameter einer Funktion:
Parameter unterliegen denselben Richtlinien wie alle anderen Bezeichner. Funktionen, die alle "do($a, $b, $c)" heißen und ebenso kryptische Parameter enthalten, widersprechen dem Coding Standard. Wenn man eine Funktion nur anhand ihres Names und anhand der Parameter benutzen kann, ist das für jeden anderen Programmierer im Team eine Hilfe.
Selbst ohne die Beschreibung der Parameter, kann man sich bei dieser Variante schon anhand des Namens viel besser vorstellen, was die Funktion macht. Die Funktion wird TRUE zurückliefern, wenn sowohl die Verbindung zum RDBMS, als auch zur Datenbank erfolgreich ist.
Die Klammern für eine Funktion () stehen direkt am Funktionsnamen.
Das die Klammern für eine Funktion () direkt am Funktionsnamen stehen, ist ein sehr verbreiteter Standard. Wie die Parameter einer Funktion behandelt werden, ist nicht einheitlich geregelt. Es wird empfohlen der Vorgabe von php.net zu entsprechen und Parameter ohne Leerzeichen zu notieren, mit Ausnahme der Kommata. Der Funktionsaufruf "add(5,2)" könnte von einem unerfahrenen Programmier falsch interpretiert werden. Hier werden zwei Parameter übergeben, nicht eine Dezimalzahl, die in PHP mit "5.2" notiert werden würde. Auch deswegen und aus Gründen der Übersichtlichkeit wird nach dem Komma ein Leerzeichen eingefügt, so wie es im deutschen Schriftverkehr auch üblich ist.
Funktionen mit langen oder vielen Parametern müssen übersichtlich strukturiert werden.
Es wird oft notwendig sein, Funktionen mit vielen Parametern zu benutzen und/oder lange Variablennamen zu definieren. Der Befehl mktime() enthält sechs Parameter.
Auf den ersten Blick ist so eine verschachtelte Struktur und die Anwendung einer Funktion mit vielen Parametern sichtbar. Auch das die Funktion sechs Parameter hat ist über die Verteilung auf mehrere Zeilen besser ersichtlich.
Der Code sollte vom Design getrennt werden (Template Engine).
Code und Design zu trennen ist eine der wichtigsten Regeln. Klassen und Funktionen unterstützen Sie darin modular zu programmieren. Wenn Sie jedoch HTML und PHP mischen, behindern Sie sich bei diesem Ansatz und ihre Skripte werden automatisch unübersichtlich.
Es gibt ganz einfache Maßnahmen, wie man nur mit PHP eine Template Engine abbilden kann, ohne sich in vibTemplate oder Smarty einzuarbeiten.
Mit einer Template Engine sind Sie viel besser in der Lage, diesen Dingen und dem PHP Coding Standard entgegen zu kommen. Es ist ein unverzichtbarer Teil der PHP-Programmierung. Viele bekannte große Projekte trennen PHP und HTML, aber nicht alle setzen dafür eine Template Engine ein. Einige Projekte lagern den HTML-Code in Funktionen aus, die dann über mehr oder weniger eindeutige Skript-Namen gefunden werden können.
Alle Templates sollten validiert werden
Templates sollten in der Regel nur HTML-Code und die Schnittestellen für die Template Engine enthalten. Die Templates können und müssen validiert werden.
Extreme Programming erklärt als eins der wichtigsten Ziele, die Qualität des Source-Codes. Je höher die Qualität von PHP- und HTML-Code ist, desto unwahrscheinlicher sind Bugs und ein Projekt, das nach mehreren Jahren nicht mehr wartbar ist. Außerdem werden bei einem GPL-Projekt andere Personen schneller bereit sein, Änderungen am Layout vorzunehmen oder ins Entwicklerteam einzusteigen.
Templates die erfolgreich validiert wurden, können in Zukunft leichter gewartet werden, da Designfehler schneller gefunden werden. Wenn zum Beispiel ein "" vergessen wurde und deswegen wird ein ganzer Textabsatz kursiv formatiert, dann wird das beim validieren als Fehler hervorgehoben.
Bezeichner einer Klasse werden mit Großbuchstaben voneinander getrennt
Für Klassen, Methoden und Eigenschaften gelten alle bisher genannten Konventionen. Allerdings werden keine Unterstriche für Spaces eingesetzt, sondern die verschiedenen Wörter werden mit Großbuchstaben voneinander getrennt.
Beispie: class DatabaseInputOutput
Es hat sich bei vielen Projekten durchgesetzt, das Methoden am Anfang klein geschrieben werden. Methoden werden oft mit Parametern aufgerufen. Dass sollte ausreichen, um Methoden und Eigenschaften nicht zu verwechseln.
Keine magischen Zahlen.
Magische Zahlen sind vielen Programmierern unter dem Begriff "magic numbers" bekannt. Für die Programmierung gilt: No magic numbers!
"27" kann zum Beispiel eine magische Zahl sein, wenn sie im Source-Code auftaucht, ohne das damit gerechnet oder sie als Index verwendet wird. Sie gilt als magisch, weil kein Fremdprogrammierer weiß, wofür sie gedacht ist. Und nach ein paar Monaten weiß es der Originalautor wahrscheinlich auch nicht mehr.
Die Zeilen zwei und drei stammen aus einem Skript. Hier wird niemand auf Anhieb die Variablen oder die magischen Zahlen entschlüsseln können.
Es ist egal, ob ein logisches Konzept hinter den Zahlen steckt, oder ob sich der Programmierer ein kryptisches System ausgedacht hat ... magische Zahlen sollten mit "define()" zu aussagekräftigen Konstanten verwandelt werden.
Nun ist die magische Zahl einer klaren, sprechenden Bedingung zugeordnet, die ohne Zweifel besser zu identifizieren und zu lesen ist.
SQL-Befehle werden groß geschrieben.
Eine Abfrage in SQL besteht aus vielen Elementen: Befehle, Funktionen, Spalten, Tabellen und sogar Variablen in einigen Fällen. SQL-Befehle und SQL-Funktionen wie SELECT, UPDATE, DELETE, MAX(), SUM() usw. werden groß geschrieben.
Man dieses SQL-Statement noch einigermaßen schnell verstehen. Trotzdem ist folgende Variante besser:
Variablen in Zählschleifen werden mit einem Buchstaben definiert.
Zählvariablen in Schleifen werden in der Regel mit einem Buchstaben ("$i", "$j", "$k" und so weiter) definiert. Dieser Standard hat sich bei den meisten Programmier- und Skript-Sprachen durchgesetzt.
So eine FOR-Schleife wird wohl den meisten Programmierern schon begegnet sein. Natürlich ist es auch möglich eine richtige Variable zu verwenden, wenn die Logik es gebietet. Zum Beispiel möchten sie alle Monate eines Jahres ausgeben. Dann bietet es sich an die Variable "$month" und nicht "$i" zu nennen.
Code, der nicht benutzt wird, soll gelöscht werden.
Jeder Programmierer wird früher oder später auf Code stoßen, der nicht mehr benutzt wird, aber nie gelöscht wurde. Besonders ärgerlich ist dann die Suche, ob und wofür der Code benutzt wird / genutze wurde.
Nicht mehr genutzer Code macht das Script unnötig groß und somit unübersichtlich. Da Quellcode immer einfach und leicht verständlich sein soll, sollte man unnötige Zeilen löschen. Wer sich nicht sicher ist, ob die Zeilen ggf. später noch benutzen möchte, der sollte zuvor eine Sicherungskopie anfertigen.
SHORT_OPEN_TAG
Wenn php mit der Option SHORT_OPEN_TAG=off konfiguriert wurde, dann kann es vorkommen, dass einige Scripte nicht mehr laufen. Sinnvoll wäre es, im Vorfeld auf "SHORT_OPEN_TAG's" zu verzichten aber bei manchen Projekte ist es nicht mehr möglich den Code entsprechend anzupassen.
In der php.ini sollte daher die Option SHORT_OPEN_TAG auf on gesetzt werden.
Der SHORT_OPEN_TAG ermöglicht mit "<?=$variable?>" auch Ausgaben von Variablen ohne ECHO. Solche Skripte funktionieren auch nicht, aber wenn die anderen Skripte "richtig" programmiert sind, kann man wenigstens eine Fehlermeldung ausgeben, wenn die Konfiguration von PHP nicht den Anforderungen entspricht.
Umgang mit Geschweifte Klammern
Jede geschweifte Klammer entsprechend untereinander in die gleiche Spalte gesetzt. Die Klammer erhält eine eigene Zeile.
Neben der besseren Übersichtlichkeit, unterstützt diese Vorgehensweise auch Copy&Paste, weil ein ganzer Block leichter markiert werden kann. Auch im Texteditor vi ist es leichter ganze Zeilen zu kopieren, als mitten in der Zeile bei der geschweiften Klammer anzufangen.
Jede Kontrollstruktur hat einen Block mit Klammern
Um Arbeit zu sparen werden manchmal Klammern nicht gesetzt. Der PHP Parser verlangt dies auch nicht, trotzdem kann diese Faulheit ganz üble Folgen haben. Also muss jede Kontrollstruktur einen Block haben, der von geschweiften Klammern umschlossen wird. Die Ausnahme bilden SWITCH-CASE Strukturen, wo ein "case:" mehrere Anweisungen enthalten kann und dann mit einem "break;" abgeschlossen wird.
Die Beispiele sind syntaktisch richtig, aber das Semikolon hinter dem ersten WHILE ist leicht zu übersehen. Eine Kontrollstruktur zu programmieren, die keinen Block benötigt, ist vielleicht möglich, aber so sollte nicht programmiert werden. Es ist hier besser einen leeren Block hinter die WHILE-Schleife zu platzieren.
Hier wird sofort ersichtlich, dass die WHILE-Schleife keine Verarbeitung enthält und nur die Datensätze der Datenbank durchlaufen werden. Wenn es irgendwie geht, sollte man solche leeren Blöcke vermeiden.
Zum Einrücken von Quellcode werden Tabulatoren verwendet
Zum Einrücken von Quellcode werden Tabulatoren, keine Leerzeichen verwendet. Wie bei der Klammersetzung, gehen auch hier die Meinungen auseinander. Verwendet man Leerzeichen, sieht der Code für alle Entwickler gleich aus. Jedoch nimmt es jedem Entwickler die Möglichkeit, "sein eigenes Bild" vom Quellcode zu gestalten. Die einen mögen 2 Leerzeichen, die anderen 4. Wird der Quelltext mit Tabulatoren eingerückt, kann jeder Entwickler seinen Editor beliebig einstellen. Editoren wie jEdit unterstützen sogar für jedes Dateiformat eigene Regeln zum Einrücken. Denkbar wäre für PHP eine Einstellung mit 4 Leerzeichen und für Perl nur 2, wobei in beiden Fällen keine "echten" Leerzeichen abgespeichert werden, sondern Tabulatoren.
Schwierig wird es, wenn es um Abstände im Code oder in den Kommentaren geht. Man sollte hier eher Leerzeichen verwenden oder es ganz sein lassen. Die folgende Beispiele enthalten Leerzeichen, die nicht mit Tabulatoren gemacht werden sollten.
Erstens würde ein Standard-Editor (Notepad, VI, nano, emacs, etc.) mit Tabulatoren-Größe=8 daraus sehr lange Zeilen machen. Zweitens erschweren diese Strukturen das Refactoring.
Beispiel: "$long_name" wird im ganzen Quellcode umbenannt in "$long_variable_name", dann würden die Abstände an dieser Stelle nicht mehr stimmen, und die Gleichheitszeichen nicht mehr untereinander stehen. Es gibt hier nur zwei Wahlmöglichkeiten: Abstände weglassen oder sie konsequent beim Refactoring wieder richtig einstellen. Da dem Refactoring sowieso viel zu wenig Beachtung geschenkt wird, sollten alle Behinderungen - also auch diese Leerzeichen - weglassen werden.
Bei den Beschreibungen einer Funktion sind zusätzliche Leerzeichen wichtig, um klar die Art ("@param") vom Rest abzusetzen. Das Problem beim Refactoring wird natürlich auch hier auftreten, aber die Dokumentation auf diese Weise hat sich sowohl in Java, als auch PHP etabliert.
Es sollte Subversion benutzt werden
Der Einsatz von Subversion bietet viele Vorteile. Wie bei einem CVS vereinfacht auch Subversion die Verwaltung von Quellcode dadurch, dass es alle Dateien eines Software-Projekts an einer zentralen Stelle liegen. Dateien und Verzeichnisse haben eine Versionsnummer. Damit ist eine Historie für jede Datei und jedes Verzeichnis gegeben. Änderungen von Datei zu Datei werden abgespeichert und die einzelnen Versionen können miteinander verglichen werden.
- Subversion bietet auch die meisten Features an, die in einem CVS zur Verfügung stehen.
- Client und Server senden Differenzen in beide Richtungen (CVS sendet nur vom Server zum Client).
- Zusammenführen von Dateien wird unterstützt.
- Subversion kann mit WebDAV benutzt werden.
Änderungen können dokumentiert werden und durch Funktionen wie "Checkout" wird die Wahrscheinlichkeit reduziert, dass Entwickler gleichzeitig ein und dieselbe Datei bearbeiten. Die Transparenz der Änderungen wird durch Subversion unterstützt.
Keine Anführungsstriche bei String-Deklarationen
Der Oft werden zur Ausgabe und Definition von Strings Anführungsstriche anstatt Hochkommata verwendet. Das sollte man sich sehr gut überlegen, denn es bietet potentielle Gefahren beim Refactoring.
Hier wird eine Variable duch einen Array ersetzt. Nehmen wir an, das muss in 50 Skripten gemacht werden, was mit einem guten Editor kein Problem ist. Nach der Aktion wird nur keins der betroffenen Skripte mehr funktionieren, weil die letzte Zeile im Beispiel einen Fehler erzeugt. Dieses kann sehr leicht durch den Einsatz von Hochkommata und dem Verkettungsoperator verhindert werden.
Das Beispiel für gültigen Code erzeugt keinen Fehler und ist auch für zukünftige Änderungen gerüstet. Denkbar ist beispielsweise, dass der Array durch eine Konstante ersetzt wird. Ein zusätzlicher Vorteil liegt darin, dass die Strings jetzt nicht mehr geparst werden.
Bei der ungültigen Variante, würde der Austausch von "$important_value" in "IMPORTANT_VALUE" (Konstante) keine Fehlermeldung erzeugen, aber die Logik des Skripts wäre nicht mehr intakt. Der Inhalt von "IMPORTANT_VALUE" würde jetzt nicht mehr ausgegeben werden, weil es innerhalb der Anführungsstriche für PHP ein String und keine Konstante mehr wäre.
Refactoring ist etwas absolut Wesentliches für eine erfolgreiche Programmierung und qualitativ hochwertigen Source-Code. Also keine Anführungsstriche bei String-Deklarationen verwenden, sondern Hochkommata in Verbindung mit dem Verkettungsoperator.
Werte für FOR-Schleifen richtig setzen
Die Variablen "$i", "$j", "$k" (und so weiter) haben sich für FOR-Schleifen durchgesetzt. Nicht so stark wird auf die Art geachtet, wie FOR-Schleifen programmiert werden und wie die Werte einer FOR-Schleife gesetzt werden sollen.
"10 - 0" oder auch "50 - 1" kann man leicht rechnen. Wenn es also möglich ist, die Werte einer FOR-Schleife so zu setzen, sollte das auch gemacht werden.
Bei dieser FOR-Schleife fehlen hier die Leerzeichen nach dem Semikolon. In der englischen und deutschen Zeichensetzung folgt ein Leerzeichen nach einem Punkt oder einem Semikolon.
Übersichtlich programmieren
Funktionsaufrufe, Strukturen von Arrays oder andere Konstrukte, die sehr lang sind, müssen übersichtlich aufgebaut werden. Dadurch können Fehler schneller gefunden werden und die Strukturen besser kontrolliert, erweitert und kommentiert werden.
Alles in einer Zeile ist nur dann erlaubt, wenn die Zeile sehr kurz ist.
Diese Schreibweise ist deutlich übersichtlicher.
