Bitte benutzen Sie die aktuellen Standards: CodingStyle

Bitte benutzen Sie die aktuellen Standards: [Entwickler/CodingStyle]

UNGÜLTIG!!! VERALTET!!!

Bitte benutzen Sie die aktuellen Standards: [[Entwickler/CodingStyle]

Coding Style Index

(:toc:)

Wir empfehlen einen Zeilenumbruch bei ca. 75 - 85 Zeichen durchzuführen, um die Lesbarkeit zu erhöhen. Maximale Zeilenlänge sollte bei 120 Zeichen erreicht sein. Zeilenumbruch nach fester Anzahl Zeichen muss bei Markup Sprachen wie HTML, XHML, XML, etc. nicht eingehalten werden.

Mit PHP 5 ist es nun möglich die Fehlerbehandlung vom eigentlichen Programmfluss zu trennen. Dies hat große Vorteile für das Debugging und die Wartbarkeit und verbessert darüberhinaus die Lesbarkeit des Quellcodes.

Da Fehlercodes als Rückgabewerte oft sehr kryptisch sind und den Programmfluss komplizierter machen, sind diese zu vermeiden.

• Konstanten / Keine Magic Numbers

Konstanten / Keine Magic Numbers

Code Formatierung

Verwende Kommentare im C-Stil (/* */) und von Standard-C++ (//). Kommentare im Perl/shell-Stil (#) vermeiden.

Dokumentationen & Tags folgen der PHPDoc Syntax. Für den Quellcode sollte eine vollständige Inline-Dokumentation bereitgestellt (Docblocks) und auch abseits der offziellen API-Dokumentation kommentiert werden. Geben Sie hilfreiche Zusatzinformationen und machen Sie dem Reviewer das Leben leichter. ;-)

Ergänzen Sie die Lizenzbestimmungen in jeder Datei innerhalb des Page-Level DocBlocks.

• Fehlerbehandlung

Mit PHP 5 ist es nun möglich die Fehlerbehandlung vom eigentlichen Programmfluss zu trennen. Dies hat große Vorteile für das Debugging und die Wartbarkeit und verbessert darüberhinaus die Lesbarkeit des Quellcodes.

Genaueres über gute Fehlerbehandlung ist dem Abschnitt über Fehlerbehandlung in diesem Coding Standard zu entnehmen.

Fehlerbehandlung

Mit PHP 5 ist es nun möglich die Fehlerbehandlung vom eigentlichen Programmfluss zu trennen. Dies hat große Vorteile für das Debugging.

Genauere Beschreibung wie gute Fehlerbehandlung aussieht ist dem Abschnitt über Fehlerbehandlung in diesem Coding Standard zu entnehmen.

• Keine Magic Numbers

Kommentare & Tags in PHPDoc Syntax. Verwende Kommentare im C-Stil (/* */) und von Standard-C++ (//). Kommentare im Perl/shell-Stil (#) vermeiden.

Für den Quellcode sollte eine vollständige Inline-Dokumentation bereitgestellt (Docblocks) und auch abseits der offziellen API-Dokumentation kommentiert werden. Geben sie hilfreiche Zusatzinformationen und machen sie es dem Reviewer das Leben einfacher.

Als Daumenregel gilt, wenn Sie auf einen Code-Abschnitt schauen und denken: „Wow, Ich würde nicht versuchen herauszufinden, wie es funktioniert“, sollten Sie auf jeden Fall einen Kommentar ergänzen, bevor Sie vergessen, wie es funktioniert.

Ergänzen Sie die Lizenzbestimmungen in jeder Datei innerhalb des File-Level DocBlocks.

Genaueres über das Anfertigen von Dokumentationen entnehmen sie dem Dokumentationsabschnitt und dem Lizenzabschnitt des Coding Standards.

Falls sinnvoll für die Lesbarkeit sollten Operatoren rechts und links von einem Leerzeichen umgeben sein.

Bsp:

Bei Kontroll-Ausdrücken ein Leerzeichen zwischen den Schlüsselwörtern und der öffnenden Klammer einfügen, um sie von Funktionsaufrufen unterscheiden zu können.

Generell unbedingt geschweifte Klammern verwenden, auch wenn sie technisch nur optional sind. Damit verbessern Sie die Lesbarkeit und vermeiden logische Fehler, wenn neue Zeilen hinzugefügt werden.

    case 1:
        action1;
        break;

    case 2:
        action2;
        break;

    default:
        defaultaction;
        break;

Bsp:

Wie im Abschnitt oben gezeigt, sollte ein Leerzeichen vor und hinter das Gleichheitszeichen gesetzt werden, wenn der Rückgabewert der Funktion einer Variable zugewiesen wird. Wenn ein Block zusammenhängender Zuweisungen durchgeführt wird, empfehlen wir mehrere Leerzeichen einzufügen, um die Lesbarkeit zu verbessern:

Bsp:

<meta http-equiv="Content-Type" content="text/html; charset=ISO-8853-1" />

Keine Magic Numbers

Eine Magic Number ist eine Zahl mitten im Quellcode. Sie wird magisch genannt, weil niemand weiß was sie bedeutet. Statt Magische Zahlen zu benutzen definiere Konstanten mit define() oder Klassen-Konstanten mit const und gib ihnen aussagekräftige Namen.

Bsp:

• define('SOME_CONSTANT_VALUE', 42)
• const SOME_CONSTANT_VALUE = 42

Maximale Anzahl Klassen/Interfaces pro File

Es bietet sich zwar in PHP an mehrere Klassen/Interfaces in einem File unterzubringen, jedoch erschwert dies nicht nur die Suche bei der Wartung, sondern schafft auch Mehrdeutigkeiten bzgl. der Packages (Namensräume). Daher empfehlen wir Klassen in verschiedene Files zu zergliedern und diese in Packages anzuordnen.

Funktionen, Konstanten und Globale Variablen werden vom Filesystem in Files gruppiert, die wiederum mittels phpDocumentor Tag @package und @subackage innerhalb von Page-Level DocBlocks in Pakete und Unterpakete gegliedert werden sollen.

Methoden und Klassenvariablen werden von PHP in Klassen gruppiert, die wiederum mittels phpDocumentor Tag @package und @subpackage innerhlab von Class-Level DocBlocks in Pakete und Unterpakete gegliedert werden sollen.

Seit PHP 5 gibt es die Möglichkeit der Objekt-orientierten Programmierung. Die damit verbundenen Konzepte bieten viele Vorteile für das Software-Design, der Wiederverwendbarkeit und Wartbarkeit. Konstrukte & Schlüsselwörter, die deprecated sind, sind zu vermeiden.

Zentral ist das Konzept der Klassen und Klassenhierarchie. Funktionalität soll gekapselt werden, damit Klassen einfach wiederzuverwenden und wartbar sind.

Für die Erzeugung und Freigabe eines Objektes gibt es die speziellen Methoden Konstruktor __constuctor und Destruktor __destructor. Aus Kompatibilitätsgründen zu älteren Versionen wird aber auch eine Methode mit dem Namen der Klasse als Konstruktor akzeptiert.

Für Methoden und Klassenvariablen gibt es die Sichtbarkeitsschlüsselwörter public, protected, private. Schlüsselwort var ist deprecated.

Konstruktoren nur für die Initialisierung von Variablen benutzen und/oder für Aktionen, die nicht fehlschlagen können. Implementiere weitere Methoden für alle anderen Aktionen und rufe diese nach der Objekt-Instanziierung auf.

Dateien, die inkludiert werden, enden auf "*.inc.php" und/oder liegen in einem Unterverzeichnis "inc". Es ist besser ein Unterverzeichnis ("include" oder "inc") für die Dateien anzulegen, die mit include() oder ähnlichen Befehlen inkludiert werden.

Immer wenn eine Klassendatei unbedingt inkludiert werden muss, benutze require_once. Bei auftretenden Fehlern wird der Programmfluss angehalten. Wird hingegen eine Datei nur bedingt benötigt, z.B. in Factory-Methoden, verwende include_once. Hier werden nur Warnungen ausgegeben, der Programmfluss jedoch nicht unterbrochen. Beide stellen sicher, dass die Datei nur einmal eingebunden wird. Beide Funktionen benutzen die gleiche Liste zur Verwaltung der bereits eingebundenen Dateien. Sie müssen sich über eine Mischung aus beiden Funktionsaufrufen keine Gedanken machen - eine Datei, die per require_once eingebunden wurde, wird nicht erneut eingebunden mit include_once.

Es wird jedoch empfohlen stets require_once zu benutzen, da i.A. ein Script nicht weiterlaufen sollte, wenn Files nicht vorhanden sind oder Filenamen nicht korrekt sind.

Für den Fall, dass der Programmfluss von einem Case-Statement ins nächste Case-Statement fällt, d.h. kein Break-Statement enthalten ist, muss dies kommentiert werden. Desweiteren sollte immer ein Default-Statement geschrieben werden, um Fehler abzufangen. Falls Variablen in einem Case-Statement erzeugt werden müssen, schreibe alles in einen Block.

Für die Trennung von Layout und Programmlogik wird der zu erzeugenden HTML-Code mit Templates generiert statt direkt aus PHP-Dateien heraus. Falls es doch in wenigen Einzelfällen notwendig ist aus PHP-Dateien heraus HTML-Code zu generieren, so ist es aus Gründen der Übersichtlichkeit (Debugging!) zu empfehlen ausreichend und sinnvoll platzierte Zeilenende ("\n") eingefügt werden. Eine Einrückung des HTML-Codes kann durch vorangestellte "\t" erzeugt werden.

Die zu übersetzenden Zeichenfolgen werden im Programmcode in die spezielle Funktion gettext() eingeschlossen. Benutzt werden sollte nur die Kurzform, in PHP realisiert als _().

Die in einen gettext() eingeschlossenen Strings sollten vollständige Sätze bzw. Informationsblöcke enthalten, also kein Zusammenstückeln aus einzelnen Teilstrings (siehe oben).

Komplizierte html-Ausdrücke, wie z.B. ein klickbares Icon im Text sollten dagegen via %s aus dem String herausgezogen werden

Beschriftete und damit zu übersetzende Formular-Buttons werden generell nicht direkt in den Code eingebunden, sondern immer über die Funktion "makeButton()" erzeugt, diese kümmert sich dann um die Lokalisierung.

Ein Magische Zahl ist eine Zahl mitten im Quellcode. Sie wird magisch gennant, weil niemand weiß was sie bedeutet. Statt Magische Zahlen zu benutzen definiere Konstanten mit define() oder Klassen-Konstanten mit const und gib ihnen reale Namen.

Coding Style

[ Zurück: OO-Design & Entwurfsmuster | Index: Übersicht | Vor: Namenskonventionen ]

Übersicht

• Sprache
• Einrückungen und Zeilenlänge
• PHP-Code-Tags
• Kommentare
• Operatoren
• Funktionsaufrufe
• Klassen-Definition
• Funktionsdefinitionen
• Codierung
• Keine Magischen Zahlen
• Maximale Anzahl Klassen pro File
• Paket-Struktur auf Page- & Class-Level
• Objekt-orientiertes Design
• Methoden-/Funktionsargumente
• Konstruktoren
• Inkludierte Dateien
• Code einbinden
• Switch-Statements
• Generierter HTML-Code
• Internationalisierung
• Text-Buttons
• CVS/SVN-Nutzung
• E_STRICT-kompatibler Code

Sprache

Die bevorzugte Sprache für Code und Kommentare ist Englisch.

Einrückungen und Zeilenlänge

Benutzen Sie Einrückungen mit 4 Leerzeichen, keine Tabulatoren. Damit helfen Sie, Probleme zu vermeiden, die mit Diffs, Patches und anderen CVS/SVN-Funktionen entstehen.

Rücke so tief ein wie notwendig, jedoch nicht mehr. Obwohl es keine Regel über die maximale Einrücktiefe gibt, wird empfohlen ab einer Einrücktiefe von 4 bis 5 Ebenen Quellcode zu faktorisieren.

Wir empfehlen einen Zeilenumbruch bei ca. 75 - 85 Zeichen durchzuführen, um die Lesbarkeit zu erhöhen. Maximale Zeilenlänge sollte bei 120 Zeichen erreicht sein.

PHP-Code-Tags

Benutzen Sie immer <?php ?> um Ihren PHP-Code zu markieren, niemals die Kurzform <? ?>. Die erste Variante funktioniert unabhängig vom Betriebssystem und der PHP-Konfiguration.

Kommentare

Kommentare & Tags sollen der PHPDoc Syntax folgen. Es sollten Kommentare im C-Stil (/* */) und von Standard-C++ (//) verwendet werden. Kommentare im Perl/shell-Stil (#) sollten Sie vermeiden.

Für den Quellcode müssen sie vollständige Inline-Dokumentation bereitstellen (Docblocks) und sie sollten auch abseits der offziellen API-Dokumentation Kommentare im Quellcode einsetzen. Als Daumenregel gilt, wenn Sie auf einen Code-Abschnitt schauen und denken: „Wow, Ich würde nicht versuchen herauszufinden, wie es funktioniert“, sollten Sie auf jeden Fall einen Kommentar ergänzen, bevor Sie vergessen, wie es funktioniert.

Operatoren

Falls sinnvoll sollten Operatoren rechts und links von einem Leerzeichen umgeben sein.

Beispiel:

$bar = 5; 
$foo = $bar % 5;

Kontrollstrukturen (if, for, while, switch usw.)

Bsp für if-Kosntruktionen:

<?php
if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}
?>

Kontroll-Ausdrücke sollten ein Leerzeichen zwischen den Schlüsselwörtern und der öffnenden Klammer haben, um sie von Funktionsaufrufen unterscheiden zu können.

Sie sollten unbedingt geschweifte Klammern verwenden, auch wenn sie technisch nur optional sind. Damit verbessern Sie die Lesbarkeit und vermeiden logische Fehler, wenn neue Zeilen hinzugefügt werden.

Bsp für switch-Ausdrücke:

<?php
switch (condition) {
case 1:
    action1;
    break;

case 2:
    action2;
    break;

default:
    defaultaction;
    break;
}
?>

Funktionsaufrufe

Funktionen sollten ohne Leerzeichen zwischen dem Funktionsnamen, der öffnenden Klammer und dem ersten Parameter aufgerufen werden. Leerzeichen sollten gesetzt werden zwischen Komma und jedem Parameter. Zwischen dem letzten Parameter, der schliessenden Klammer und Semikolon sollten keine Leerzeichen gesetzt werden.

Beispiel:

<?php
$var = foo($bar, $baz, $quux);
?>

Wie oben gezeigt, sollte ein Leerzeichen vor und hinter das Gleichheitszeichen gesetzt werden, wenn der Rückgabewert der Funktion einer Variable zugewiesen wird. Wenn ein Block zusammenhängender Zuweisungen durchgeführt wird, empfehlen wir mehrere Leerzeichen einzufügen, um die Lesbarkeit zu verbessern:

<?php
$short         = foo($bar);
$long_variable = foo($baz);
?>

Klassen-Definition

Die öffnende Klammer einer Klassen-Deklaration beginnt auf einer neuen Zeile:

<?php
class FooBar
{

    //... ihr Code

}
?>

Funktionsdefinitionen

Funktionsdeklarationen folgen dem „K&R-Stil“ (Programmierstil der C-Erfindern Brian W. Kernighan und Dennis Ritchie):

<?php
function fooFunction($arg1, $arg2 = '')
{
    if (condition) {
        statement;
    }
    return $val;
}
?>

Argumente mit Standardwerten werden am Ende der Argumentenliste platziert. Eine Funktion sollte immer einen aussagekräftigen Wert zurückliefern, soweit wie es möglich ist.

Beispiel:

<?php
function connect(&$dsn, $persistent = false)
{
    if (is_array($dsn)) {
        $dsninfo = &$dsn;
    } else {
        $dsninfo = DB::parseDSN($dsn);
    }

    if (!$dsninfo || !$dsninfo['phptype']) {
        return $this->raiseError();
    }

    return true;
}
?>

Codierung

Für die Codierung der HTML-Seiten wird im Seiten-Kopf ISO-8859-1/Latin1 benutzt und nie UTF-8. Damit es zu einer korrekten Darstellung kommt ist dies auf jeden Fall einzuhalten.

<meta http-equiv="Content-Type" content="text/html; charset=ISO-8853-1" />

Keine Magischen Zahlen

Ein Magische Zahl ist eine nackte Zahl mitten im Quellcode. Sie wird magisch gennant, weil niemand weiß was sie bedeutet. Statt Magische Zahlen zu benutzen definiere Konstanten mit define() oder Klassen-Konstanten mit const und gib ihnen reale Namen.

Maximale Anzahl Klassen pro File

Es bietet sich zwar in PHP an mehrere Klassen in einem File unterzubringen, jedoch erschwert dies nicht nur die Suche bei der Wartung, sondern schafft auch Mehrdeutigkeiten bzgl. der Packages. Daher empfehlen wir Klassen in verschiedene Files zu zergliedern und diese in Packages anzuordnen.

Paket-Struktur auf Page- & Class-Level

Funktionen, Konstanten und Globale Variablen werden vom Filesystem in Files gruppiert, die wiederum mittels phpDocumentor Tag @package und @subackage innerhlab von Page-Level DocBlocks in Pakete und Unterpakete gegliedert werden sollen.

Methoden und Klassenvariablen werden von PHP in Klassen gruppiert, die wiederum mittels phpDocumentor Tag @package und @subackage innerhlab von Class-Level DocBlocks in Pakete und Unterpakete gegliedert werden sollen.

Wird diese Paket-Struktur nicht eingehalten so hat phpDocumentor Probleme den Code zu parsen.

Objekt-orientiertes Design

Seit PHP 5 gibt es die Möglichkeit der Objekt-orientierten Programmierung. Die damit verbundenen Konzepte bieten viele Vorteile für das Software-Design. Daher wird empfohlen diese zu nutzen. Konstrukte & Schlüsselwörter, die deprecated sind, sind zu vermeiden.

Klassen

Zentral ist das Konzept der Klassen und Klassenhierarchie. Funktionalität soll gekapselt werden, und Klassen einfach wiederzuverwenden und wartbar sein.

Konstruktor und Destruktor

Für solche Automatismen bei Erzeugung und Freigabe eines Objektes gibt es die speziellen Methoden Konstruktor __constuctor und Destruktor __dectructor.

Aus Kompatibilitätsgründen zu älteren Versionen wird aber auch eine Methode mit dem Namen der Klasse als Konstruktor akzeptiert.

Sichtbarkeitsschlüsselwörter

Bei Methoden und Klassenvariablen sollen die Sichtbarkeitsschlüsselwörter public, protected, private benutzt werden. Schlüsselwort var ist deprecated.

Methoden-/Funktionsargumente

Referenzen als Argumente sollten nur benutzt werden, wenn es sich nicht vermeiden lässt, d.h. wenn die Funktion auch wirklich den Inhalt der Variablen verändern muss. Die Performance von Übergaben als Referenz ist zwar manchmal schneller, jedoch wird sich dies nur bei umfangreichen Schleifen oder bei der Übertragung von grossen Arrays oder Objekten bemerkbar machen.

Konstruktoren

Benutze Konstruktoren nur für die Initialisierung von Variablen und/oder für Aktionen die nicht fehlschlagen können. Implementiere weitere Methoden für alle anderen Aktionen und rufe diese nach der Objekt-Instanziierung auf.

Inkludierte Dateien

Dateien, die inkludiert werden sollten, mit "*.inc.php" enden oder in einem Unterverzeichnis liegen.

Es ist jedoch besser ein Unterverzeichnis ("include" oder "inc") für die Dateien anzulegen, die per include() oder ähnlichen Befehlen inkludiert werden.

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 (auch Passwörter) im Klartext vorliegen.

Code einbinden

Immer wenn Sie eine Klassendatei unbedingt inkludieren müssen, dann benutzen Sie require_once. Bei auftretenden Fehlern wird der Programmfluss angehalten. Benötigen Sie hingegen eine Datei nur bedingt, z.B. in Factory-Methoden, verwenden Sie include_once. Hier werden nur Warnungen ausgegeben, der Programmfluss jedoch nicht unterbrochen. Beide stellen sicher, dass die Datei nur einmal eingebunden wird. Beide Funktionen benutzen die gleiche Liste zur Verwaltung der bereits eingebundenen Dateien. Sie müssen sich über eine Mischung aus beiden Funktionsaufrufen keine Gedanken machen - eine Datei, die per require_once eingebunden wurde, wird nicht erneut eingebunden mit include_once.

Es wird empfohlen stets require_once zu benutzen, da i.A. ein Script nicht weiterlaufen sollte, wenn Files nicht vorhanden sind oder Filenamen nicht korrekt sind.

Anmerkung: include_once und require_once sind Anweisungen, nicht Funktionen. Deshalb sollten die Dateinamen nicht in Klammern eingeschlossen werden.

Switch-Statements

Für den Fall, dassder Programmfluss fon einem Case-Statement ins nächste Case-Statement fällt, d.h. kein Break-Statement enthalten ist, muss dies kommentiert werden. Desweiteren sollte immer ein Default-Statement geschrieben werden, um Fehler abzufangen. Falls Variablen in einem Case-Statement erzeugt werden müssen, schreibe alles in einen Block.

Generierter HTML-Code

HTML-Code sollte mit Templates generiert werden statt aus PHP-Dateien heraus. Falls doch notwendig ist aus PHP-Dateien heraus HTML-Code zu generieren, so ist es aus Gründen der Übersichtlichkeit (Debugging!) zu empfehlen ausreichend und sinnvoll plazierte Zeilenende ("\n") eingefügt werden. Eine Einrückung des HTML-Codes kann durch vorangestellte "\t" erzeugt werden.

Internationalisierung

Generell wird zur Darstellung sprachspezifischer Strings das gettext- (oder auch i18n) -System verwendet.

Alle Strings im System dürfen nicht in den HTML-Teilen der Sourcedateien stehen, sondern müssen aus PHP-Abschnitten heraus geschrieben werden. Die zu übersetzenden Zeichenfolgen werden im Programmcode in die spezielle Funktion gettext() eingeschlossen. Benutzt werden sollte nur die Kurzform, in PHP realisiert als _().

(:source lang=php :)echo _("Meine Veranstaltungen")

In die zu übersetzenden Strings sollte reiner Text, keine HTML-Struktur der Seite und kein Programmcode wie z.B. Variablennamen eingeschlossen werden.

Falsch:
(:source lang=php :)echo _("<tr><td>Meine Veranstaltungen</td></tr>");
Richtig:
(:source lang=php :)echo "<tr><td>" . _("Meine Veranstaltungen") . "</td></tr>";
Oder Richtig:
(:source lang=php :)printf("<tr><td>%s</td></tr>", _(" Meine Veranstaltungen "));

Falsch:
(:source lang=php :)print _("error§Keine Berechtigung!§");
Richtig:
(:source lang=php :)printf("error§%s§", _("Keine Berechtigung!"));

Falsch:
(:source lang=php :)echo _("Sie haben $count neue Nachrichten.");
Auch falsch:
(:source lang=php :)echo _("Sie haben ") . $count . _(" neue Nachrichten.");
Richtig:
(:source lang=php :)printf(_("Sie haben %s neue Nachrichten."), $count);

Die in einen gettext() eingeschlossenen Strings sollten vollständige Sätze bzw. Informationsblöcke enthalten, also kein Zusammenstückeln aus einzelnen Teilstrings (siehe oben).

Schliessen sich die beiden vorangegangenen Vorschriften gegenseitig aus, weil z.B. ein Teil eines Satzes formatiert wird, so hat die letztere Regel Vorrang (der Übersetzer braucht sowieso html-Grundlagenkenntnisse.

Falsch:
(:source lang=php :)echo _("Sie können diese Datei ") . "<b>" . _("nicht") . "</b>" . _(" löschen");
Richtig:
(:source lang=php :)echo _("Sie können diese Datei <b>nicht</b> löschen");

Komplizierte html-Ausdrücke, wie z.B. ein klickbares Icon im Text sollten dagegen via %s aus dem String herausgezogen werden

Richtig:
(:source lang=php :)printf(_("Unter %s gelangen Sie zu Ihren Terminen."), "<a href><img src = \"pictures/icon-lit.gif\"></a>");

Text-Buttons

Beschriftete und damit zu übersetzende Formular-Buttons werden generell nicht direkt in den Code eingebunden, sondern immer über die Funktion "makeButton()" erzeugt, diese kümmert sich dann um die Lokalisierung.

CVS/SVN-Nutzung

Ergänzen Sie das $Id$-CVS/SVN-Schlüsselwort in jeder Datei.

E_STRICT-kompatibler Code

Jeder Code muss E_STRICT-kompatibel sein. Das heisst, er darf keine Fehler oder Warnungen erzeugen, wenn das Fehler-Reporting von PHP auf E_STRICT eingestellt ist.

Die Entwicklung existierender Packages, die dieser Konvention noch nicht entsprechen, müssen dies auch noch nicht.

• E_STRICT-kompatibler Code

E_STRICT-kompatibler Code

Jeder Code muss E_STRICT-kompatibel sein. Das heisst, er darf keine Fehler oder Warnungen erzeugen, wenn das Fehler-Reporting von PHP auf E_STRICT eingestellt ist.

Die Entwicklung existierender Packages, die dieser Konvention noch nicht entsprechen, müssen dies auch noch nicht.

Klassen

Zentral ist das Konzept der Klassen und Klassenhierarchie. Funktionalität soll gekapselt werden, und Klassen einfach wiederzuverwenden und wartbar sein.

• Objekt-orientiertes Design

Objekt-orientiertes Design

Seit PHP 5 gibt es die Möglichkeit der Objekt-orientierten Programmierung. Die damit verbundenen Konzepte bieten viele Vorteile für das Software-Design. Daher wird empfohlen diese zu nutzen. Konstrukte & Schlüsselwörter, die deprecated sind, sind zu vermeiden.

Konstruktor und Destruktor

Für solche Automatismen bei Erzeugung und Freigabe eines Objektes gibt es die speziellen Methoden Konstruktor __constuctor und Destruktor __dectructor.

Aus Kompatibilitätsgründen zu älteren Versionen wird aber auch eine Methode mit dem Namen der Klasse als Konstruktor akzeptiert.

Sichtbarkeitsschlüsselwörter

Bei Methoden und Klassenvariablen sollen die Sichtbarkeitsschlüsselwörter public, protected, private benutzt werden. Schlüsselwort var ist deprecated.

• Sprache
• Einrückungen und Zeilenlänge
• PHP-Code-Tags
• Kommentare
• Operatoren
• Funktionsaufrufe
• Klassen-Definition
• Funktionsdefinitionen
• Codierung
• Keine Magischen Zahlen
• Maximale Anzahl Klassen pro File
• Paket-Struktur auf Page- & Class-Level
• Sichtbarkeitsschlüsselwörter
• Methoden-/Funktionsargumente
• Konstruktoren
• Inkludierte Dateien
• Code einbinden
• Switch-Statements
• Generierter HTML-Code
• Internationalisierung
• Text-Buttons
• CVS/SVN-Nutzung

Coding Style

Übersicht

[ Zurück: OO-Design & Entwurfsmuster | Index: Übersicht | Vor: Namenskonventionen ]

[ Zurück: OO-Design & Entwurfsmuster | Index: Übersicht | Vor:

[ Zurück: | Index: Übersicht | Vor:

PHP-Code-Tags

Benutzen Sie immer <?php ?> um Ihren PHP-Code zu markieren, niemals die Kurzform <? ?>. Die erste Variante funktioniert unabhängig vom Betriebssystem und der PHP-Konfiguration.

Kommentare

Kommentare & Tags sollen der PHPDoc Syntax folgen. Es sollten Kommentare im C-Stil (/* */) und von Standard-C++ (//) verwendet werden. Kommentare im Perl/shell-Stil (#) sollten Sie vermeiden.

Für den Quellcode müssen sie vollständige Inline-Dokumentation bereitstellen (Docblocks) und sie sollten auch abseits der offziellen API-Dokumentation Kommentare im Quellcode einsetzen. Als Daumenregel gilt, wenn Sie auf einen Code-Abschnitt schauen und denken: „Wow, Ich würde nicht versuchen herauszufinden, wie es funktioniert“, sollten Sie auf jeden Fall einen Kommentar ergänzen, bevor Sie vergessen, wie es funktioniert.

Keine Magischen Zahlen

Ein Magische Zahl ist eine nackte Zahl mitten im Quellcode. Sie wird magisch gennant, weil niemand weiß was sie bedeutet. Statt Magische Zahlen zu benutzen definiere Konstanten mit define() oder Klassen-Konstanten mit const und gib ihnen reale Namen.

Maximale Anzahl Klassen pro File

Es bietet sich zwar in PHP an mehrere Klassen in einem File unterzubringen, jedoch erschwert dies nicht nur die Suche bei der Wartung, sondern schafft auch Mehrdeutigkeiten bzgl. der Packages. Daher empfehlen wir Klassen in verschiedene Files zu zergliedern und diese in Packages anzuordnen.

Paket-Struktur auf Page- & Class-Level

Funktionen, Konstanten und Globale Variablen werden vom Filesystem in Files gruppiert, die wiederum mittels phpDocumentor Tag @package und @subackage innerhlab von Page-Level DocBlocks in Pakete und Unterpakete gegliedert werden sollen.

Methoden und Klassenvariablen werden von PHP in Klassen gruppiert, die wiederum mittels phpDocumentor Tag @package und @subackage innerhlab von Class-Level DocBlocks in Pakete und Unterpakete gegliedert werden sollen.

Wird diese Paket-Struktur nicht eingehalten so hat phpDocumentor Probleme den Code zu parsen.

Sichtbarkeitsschlüsselwörter

Bei Methoden und Klassenvariablen sollen die Sichtbarkeitsschlüsselwörter public, protected, private benutzt werden.

Methoden-/Funktionsargumente

Referenzen als Argumente sollten nur benutzt werden, wenn es sich nicht vermeiden lässt, d.h. wenn die Funktion auch wirklich den Inhalt der Variablen verändern muss. Die Performance von Übergaben als Referenz ist zwar manchmal schneller, jedoch wird sich dies nur bei umfangreichen Schleifen oder bei der Übertragung von grossen Arrays oder Objekten bemerkbar machen.

Konstruktoren

Benutze Konstruktoren nur für die Initialisierung von Variablen und/oder für Aktionen die nicht fehlschlagen können. Implementiere weitere Methoden für alle anderen Aktionen und rufe diese nach der Objekt-Instanziierung auf.

Inkludierte Dateien

Dateien, die inkludiert werden sollten, mit "*.inc.php" enden oder in einem Unterverzeichnis liegen.

Es ist jedoch besser ein Unterverzeichnis ("include" oder "inc") für die Dateien anzulegen, die per include() oder ähnlichen Befehlen inkludiert werden.

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 (auch Passwörter) im Klartext vorliegen.

Code einbinden

Immer wenn Sie eine Klassendatei unbedingt inkludieren müssen, dann benutzen Sie require_once. Bei auftretenden Fehlern wird der Programmfluss angehalten. Benötigen Sie hingegen eine Datei nur bedingt, z.B. in Factory-Methoden, verwenden Sie include_once. Hier werden nur Warnungen ausgegeben, der Programmfluss jedoch nicht unterbrochen. Beide stellen sicher, dass die Datei nur einmal eingebunden wird. Beide Funktionen benutzen die gleiche Liste zur Verwaltung der bereits eingebundenen Dateien. Sie müssen sich über eine Mischung aus beiden Funktionsaufrufen keine Gedanken machen - eine Datei, die per require_once eingebunden wurde, wird nicht erneut eingebunden mit include_once.

Es wird empfohlen stets require_once zu benutzen, da i.A. ein Script nicht weiterlaufen sollte, wenn Files nicht vorhanden sind oder Filenamen nicht korrekt sind.

Anmerkung: include_once und require_once sind Anweisungen, nicht Funktionen. Deshalb sollten die Dateinamen nicht in Klammern eingeschlossen werden.

Switch-Statements

Für den Fall, dassder Programmfluss fon einem Case-Statement ins nächste Case-Statement fällt, d.h. kein Break-Statement enthalten ist, muss dies kommentiert werden. Desweiteren sollte immer ein Default-Statement geschrieben werden, um Fehler abzufangen. Falls Variablen in einem Case-Statement erzeugt werden müssen, schreibe alles in einen Block.

Generierter HTML-Code

HTML-Code sollte mit Templates generiert werden statt aus PHP-Dateien heraus. Falls doch notwendig ist aus PHP-Dateien heraus HTML-Code zu generieren, so ist es aus Gründen der Übersichtlichkeit (Debugging!) zu empfehlen ausreichend und sinnvoll plazierte Zeilenende ("\n") eingefügt werden. Eine Einrückung des HTML-Codes kann durch vorangestellte "\t" erzeugt werden.

Internationalisierung

Generell wird zur Darstellung sprachspezifischer Strings das gettext- (oder auch i18n) -System verwendet.

Alle Strings im System dürfen nicht in den HTML-Teilen der Sourcedateien stehen, sondern müssen aus PHP-Abschnitten heraus geschrieben werden. Die zu übersetzenden Zeichenfolgen werden im Programmcode in die spezielle Funktion gettext() eingeschlossen. Benutzt werden sollte nur die Kurzform, in PHP realisiert als _().

(:source lang=php :)echo _("Meine Veranstaltungen")

In die zu übersetzenden Strings sollte reiner Text, keine HTML-Struktur der Seite und kein Programmcode wie z.B. Variablennamen eingeschlossen werden.

Falsch:
(:source lang=php :)echo _("<tr><td>Meine Veranstaltungen</td></tr>");
Richtig:
(:source lang=php :)echo "<tr><td>" . _("Meine Veranstaltungen") . "</td></tr>";
Oder Richtig:
(:source lang=php :)printf("<tr><td>%s</td></tr>", _(" Meine Veranstaltungen "));

Falsch:
(:source lang=php :)print _("error§Keine Berechtigung!§");
Richtig:
(:source lang=php :)printf("error§%s§", _("Keine Berechtigung!"));

Falsch:
(:source lang=php :)echo _("Sie haben $count neue Nachrichten.");
Auch falsch:
(:source lang=php :)echo _("Sie haben ") . $count . _(" neue Nachrichten.");
Richtig:
(:source lang=php :)printf(_("Sie haben %s neue Nachrichten."), $count);

Die in einen gettext() eingeschlossenen Strings sollten vollständige Sätze bzw. Informationsblöcke enthalten, also kein Zusammenstückeln aus einzelnen Teilstrings (siehe oben).

Schliessen sich die beiden vorangegangenen Vorschriften gegenseitig aus, weil z.B. ein Teil eines Satzes formatiert wird, so hat die letztere Regel Vorrang (der Übersetzer braucht sowieso html-Grundlagenkenntnisse.

Falsch:
(:source lang=php :)echo _("Sie können diese Datei ") . "<b>" . _("nicht") . "</b>" . _(" löschen");
Richtig:
(:source lang=php :)echo _("Sie können diese Datei <b>nicht</b> löschen");

Komplizierte html-Ausdrücke, wie z.B. ein klickbares Icon im Text sollten dagegen via %s aus dem String herausgezogen werden

Richtig:
(:source lang=php :)printf(_("Unter %s gelangen Sie zu Ihren Terminen."), "<a href><img src = \"pictures/icon-lit.gif\"></a>");

Text-Buttons

Beschriftete und damit zu übersetzende Formular-Buttons werden generell nicht direkt in den Code eingebunden, sondern immer über die Funktion "makeButton()" erzeugt, diese kümmert sich dann um die Lokalisierung.

CVS/SVN-Nutzung

Ergänzen Sie das $Id$-CVS/SVN-Schlüsselwort in jeder Datei.

Rücke so tief ein wie notwendig, jedoch nicht mehr. Obwohl es keine Regel über die maximale Einrücktiefe gibt, wird empfohlen ab einer Einrücktiefe von 4 bis 5 Ebenen Quellcode zu faktorisieren.

Codierung

Für die Codierung der HTML-Seiten wird im Seiten-Kopf ISO-8859-1/Latin1 benutzt und nie UTF-8. Damit es zu einer korrekten Darstellung kommt ist dies auf jeden Fall einzuhalten.

<meta http-equiv="Content-Type" content="text/html; charset=ISO-8853-1" />

$bar = 5; 
$foo = $bar % 5;

(:source lang=php linenum:)[@<?php

(:source lang=php linenum:)[@<?php

(:source lang=php linenum:)[@<?php

(:source lang=php linenum:)[@<?php

(:source lang=php linenum:)[@<?php

(:source lang=php linenum:)[@<?php

(:source lang=php linenum:)[@<?php

[ Zurück: Kapselung von lokalen Besonderheiten? | Index: Übersicht | Vor: Code Formulierung

Wir empfehlen einen Zeilenumbruch bei ca. 75 - 85 Zeichen durchzuführen, um die Lesbarkeit zu erhöhen. Maximale Zeilenlänge sollte bei 120 Zeichen erreicht sein.

Rücke so tiet ein wie notwendig, jedoch nicht mehr. Obwohl es keine Regel über die maximale Einrücktiefe gibt, wird empfohlen ab einer Einrücktiefe von 4 bis 5 Ebenen Quellcode zu faktorisieren.

Rücke so tiet ein wie notwendig, jedoch nicht mehr. Obwohl es keine Regel über die maximale Einrücktiefe gibt, wird empfohlen ab eine Einrücktiefe von 4 bis 5 Ebenen darüber nachzudenken Quellcode zu faktorisieren.

Codierung

Für die Codierung sollte immer ISO-8859-1/Latin1 benutzt werden und nie UTF-8, damit lokalisierbare Strings die gleichen Bytes enthalten. Das Zeichen "§", welches als Trennzeichen bei verketteten msg Stings verwendet wird, ist in Latin-1 ("0xA7") anders codiert als in UTF-8 ("0xC2" / "0xA"). Dadurch werden Strings wie "error§" nicht richtig ersetzt werden.

Beispiel:

$bar = 5; $foo = $bar % 5;

Kommentare sollen der PHPDoc Syntax folgen.

Operatoren

Falls sinnvoll sollten Operatoren rechts und links von einem Leerzeichen umgeben sein.

Code Formatierung

[ Zurück: Kapselung von lokalen Besonderheiten? | Index: Übersicht | Vor: Code Formulierung ]

Benutzen Sie Einrückungen mit 4 Leerzeichen, keine Tabulatoren. Damit helfen Sie, Probleme zu vermeiden, die mit Diffs, Patches und anderen CVS/SVN-Funktionen entstehen.

Wir empfehlen einen Zeilenumbruch bei ca. 75 - 85 Zeichen durchzuführen, um die Lesbarkeit zu erhöhen. Maximale Zeilenlänge ist spätestens bei 120 Zeichen erreicht.

[ Zurück: Kapselung von lokalen Besonderheiten? | Index: Übersicht | Vor: Namenskonventionen ]

Sprache

Die bevorzugte Sprache für Code und Kommentare ist Englisch.

Formatierung

Einrückungen und Zeilenlänge

Benutzen Sie Einrückungen mit 4 Leerzeichen, keine Tabulatoren. Damit helfen Sie, Probleme zu vermeiden, die mit Diffs, Patches und anderen CVS-Funktionen entstehen.

Wir empfehlen einen Zeilenumbruch bei ca. 75 - 85 Zeichen durchzuführen, um die Lesbarkeit zu erhöhen.

Kontrollstrukturen (if, for, while, switch usw.)

Bsp für if-Kosntruktionen:

<?php
if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}
?>

Kontroll-Ausdrücke sollten ein Leerzeichen zwischen den Schlüsselwörtern und der öffnenden Klammer haben, um sie von Funktionsaufrufen unterscheiden zu können.

Sie sollten unbedingt geschweifte Klammern verwenden, auch wenn sie technisch nur optional sind. Damit verbessern Sie die Lesbarkeit und vermeiden logische Fehler, wenn neue Zeilen hinzugefügt werden.

Bsp für switch-Ausdrücke:

<?php
switch (condition) {
case 1:
    action1;
    break;

case 2:
    action2;
    break;

default:
    defaultaction;
    break;
}
?>

Funktionsaufrufe

Funktionen sollten ohne Leerzeichen zwischen dem Funktionsnamen, der öffnenden Klammer und dem ersten Parameter aufgerufen werden. Leerzeichen sollten gesetzt werden zwischen Komma und jedem Parameter. Zwischen dem letzten Parameter, der schliessenden Klammer und Semikolon sollten keine Leerzeichen gesetzt werden.

Beispiel:

<?php
$var = foo($bar, $baz, $quux);
?>

Wie oben gezeigt, sollte ein Leerzeichen vor und hinter das Gleichheitszeichen gesetzt werden, wenn der Rückgabewert der Funktion einer Variable zugewiesen wird. Wenn ein Block zusammenhängender Zuweisungen durchgeführt wird, empfehlen wir mehrere Leerzeichen einzufügen, um die Lesbarkeit zu verbessern:

<?php
$short         = foo($bar);
$long_variable = foo($baz);
?>

Klassen-Definition

Die öffnende Klammer einer Klassen-Deklaration beginnt auf einer neuen Zeile:

<?php
class FooBar
{

    //... ihr Code

}
?>

Funktionsdefinitionen

Funktionsdeklarationen folgen dem „K&R-Stil“ (Programmierstil der C-Erfindern Brian W. Kernighan und Dennis Ritchie):

<?php
function fooFunction($arg1, $arg2 = '')
{
    if (condition) {
        statement;
    }
    return $val;
}
?>

Argumente mit Standardwerten werden am Ende der Argumentenliste platziert. Eine Funktion sollte immer einen aussagekräftigen Wert zurückliefern, soweit wie es möglich ist.

Beispiel:

<?php
function connect(&$dsn, $persistent = false)
{
    if (is_array($dsn)) {
        $dsninfo = &$dsn;
    } else {
        $dsninfo = DB::parseDSN($dsn);
    }

    if (!$dsninfo || !$dsninfo['phptype']) {
        return $this->raiseError();
    }

    return true;
}
?>

Kommentare

Sie müssen vollständige Inline-Dokumentation bereitstellen (Docblocks).

Sie sollten auch abseits der offziellen API-Dokumentation Kommentare im Quellcode einsetzen. Als Daumenregel gilt, wenn Sie auf einen Code-Abschnitt schauen und denken: „Wow, Ich würde nicht versuchen herauszufinden, wie es funktioniert“, sollten Sie auf jeden Fall einen Kommentar ergänzen, bevor Sie vergessen, wie es funktioniert.

Kommentare im C-Stil (/* */) und von Standard-C++ (//) sollten verwendet werden. Kommentare im Perl/shell-Stil (#) sollten Sie vermeiden.

PHP-Code-Tags

Benutzen Sie immer <?php ?> um Ihren PHP-Code zu markieren, niemale die Kurzform <? ?>. Die erste Variante funktioniert unabhängig vom Betriebssystem und der PHP-Konfiguration.

Beispiel-URLs

Benutzen Sie example.com, example.org und example.net für alle Beispiel-URLs und Email-Adressen entsprechend RFC 2606.

Namens-Konventionen

Klassen

Verwenden Sie beschreibende Klassennamen und vermeiden Sie Abkürzungen. Klassennamen beginnen immer mit einen Großbuchstaben. Die Klassenhierarchie in PEAR spiegelt sich auch im Klassennamen wieder, jede Ebene der Hierarchie wird durch einen einzelnen Unterstrich getrennt.

Beispiele für Klassennamen:

• Log
• Net_Finger
• HTML_Upload_Error

Funktionen und Methoden

Funktionen und Methoden sollten dem „Studly Caps“-Stil folgen (auch bekannt als „Bumpy Base“ oder „Camel Caps“). Funktionsnamen sollte der Package-Name vorangestellt werden, um Kollisionen mit anderen Funktionsnamen zu vermeiden. Der erste Buchstabe nach dem Prefix wird klein geschrieben, und jeder Buchstabe eines neuen „Wortes“ im Namen wird großgeschrieben.

Beispiele:

• connect()
• getData()
• buildSomeWidget()
• XML_RPC_serializeData()

Privaten Klassenelemente wird ein Unterstrich vorangestellt.

Zum Beispiel:

• _sort()
• _initTree()

$this->_status

Anmerkung: Unter PHP 5 gilt: Klassenelemente, welche protected sind, werden nicht mit einem Unterstrich versehen:

• protected $somevar
• protected function initTree()

Konstanten

Konstanten werden immer vollständig groß geschrieben, mit Unterstrichen zwischen den Worten. Ihre Namen müssen mit dem Klassen- bzw. Package-Namen beginnen. Zum Beispiel beginnen alle Konstanten des DB::-Packages mit DB_.

Anmerkung: Die Konstanten true, false und null werden als einzige Ausnahme immer klein geschrieben.

Globale Variablen

Wenn Ihr Package globale Variablen benötigt, sollte deren Name mit einem Unterstrich beginnen, gefolgt vom Package-Namen und einem weiteren Unterstrich. Zum Beispiel benutzt das PEAR-Package die globale Variable $_PEAR_destructor_object_list.