B.1. Übersicht B.1.1. Geltungsbereich Dieses Dokument bietet Richtlinien für die Formatierung von Code und Dokumentation für Individuen und Teams die im Zend Framework mitarbeiten. Viele Entwickler die den Zend Framework verwenden haben diese Code Standards als nützlich empfunden weil Ihr Code Stil mit jedem Zend Framework Code konsistent bleibt. Es ist auch anzumerken das es signifikant viel Arbeit erfordert einen kompletten Coding Standard zu definieren. Beachte: Manchmal entscheiden Entwickler das die Verfügbarkeit eines Standards wichtiger ist als was der Standard aktuell im höchsten Level des Designs empfiehlt. Diese Richtlinien im Zend Framework Coding Standard beschreiben die Praxis die im ZF Projekt sehr gut funktionieren. Diese Standard können geändert oder so wie sie sind verwendet werden solange Sie sich an unsere Lizenz halten. Die Bereiche die im ZF Coding Standard abgedeckt werden enthalten: PHP Dateiformatierung Namens Konventionen Code Stil B.1.2. Ziele Inline Dokumentation Coding Standards sind in jedem Entwicklungs Projekt wichtig, aber sie sid speziell dann wichtig wenn viele Entwickler an dem gleichen Projekt arbeiten. Coding Standards helfen sicherzustellen das der Code von hoher Qualität ist, weniger Fehler hat, und einfach zu warten ist. B.2. PHP Dateiformatierung B.2.1. Allgemein Für Dateien, welche nur PHP Code beinhalten ist der schliessende Tag ("?>") nicht zugelassen. Er wird von PHP nicht benötigt, und das Weglassen verhindert das versehentlich Leerzeilen in die Antwort eingefügt werden. WICHTIG: Einbeziehen von beliebigen binärischen Daten durch HALT_COMPILER() ist in den PHP Dateien im Zend Framework oder abgeleiteten Datei verboten. Das Benutzen ist nur für einige Installationsskirpte erlaubt. B.2.2. Einrücken Ein Einzug sollte aus 4 Leerzeichen bestehen. Tabulatoren sind nicht erlaubt. B.2.3. Maximale Zeilenlänge Die Zielzeilenlänge ist 80 Zeichen. Entwickler sollten jede Zeile Ihres Codes unter 80 Zeichen halten, soweit dies möglich und praktikabel ist. Trotzdem sind längere Zeilen in einigen Fällen erlaubt. Die maximale Länge einer Zeile beträgt 120 Zeichen.
B.2.4. Zeilenbegrenzung Die Zeilenbegrenzung folgt der Unix Textdatei Konvention. Zeilen müssen mit einem einzelnen Zeilenvorschubzeichen (LF) enden. Zeilenvorschub Zeicen werden duch eine ordinale 10, oder durch 0x0A (hexadecimal) dargestellt. Beachte: Benutze nicht den Wagenrücklauf (CR) wie in den Konventionen von Apple's OS (0x0D) oder die Kombination aus Wagenrücklauf und Zeilenvorschub (CRLF) wie im Standard für das Windows OS (0x0D, 0x0A). B.3. Namens Konventionen B.3.1. Klassen Zend Framework standartisiert eine Klassennamen Konvention wobei die Namen der Klassen direkt mit den Verzeichnissen übereinstimmen muß in welchen Sie gespeichert sind. Das Basisverzeichnis der ZF Standard Bibliothek ist das "Zend/" Verzeichnis, wobei das Basisverzeichnis der ZF Extras Bibliothek im "ZendX/" Verzeichnis ist. Alle Zend Framework Klassen werden hierarchisch unter dem gleichen Basisverzeichnis gespeichert. Klassennamen dürfen nur alphanumerische Zeichen enthalten. Nummern sind in Klassennamen gestattet es wird aber von Ihnen in den meisten Fällen abgeraten. Unterstriche sind nur gestattet im Platz des Pfadseparators -- der Dateiname "Zend/Db/Table.php" muß übereinstimmen mit dem Klassennamen "Zend_Db_Table". Wenn ein Klassenname aus mehr als einem Wort besteht, muß der erste Buchstabe von jedem neuen Wort großgeschrieben werden. Durchgehende Großbuchstaben sind nicht erlaubt, z.b. eine Klasse "Zend_PDF" ist nicht erlaubt, aber "Zend_Pdf" ist akzeptierbar. Diese Konventionen definieren einen Pseudo-Namespace Mechanismus für Zend Framework. Zend Framework wird das PHP Namespace Feature einbauen sobald es verfügbar ist und es für unsere Entwickler in deren Anwendungen ohne Bedenken verwendbar ist. Siehe die Klassennamen in der Standard und Extra Bibliothek für Beispiel dieser Klassennamen Konvention. WICHTIG: Code welcher mit dem Framework ausgeliefert werden muß, aber nicht Teil der Standard oder Extras Bibliothek ist (z.b. Anwendungscode oder Bibliotheken die nicht von Zend ausgeliefert werden), dürfen nie mit "Zend_" oder "ZendX_" beginnen. B.3.2. Dateinamen Für alle anderen Dateien sind nur alphanummerische Zeichen, Unterstriche, und der Bindestrich ("-") gestattet. Leerzeichen sind völlig verboten. Jede Datei die irgendeinen PHP Code enthält sollte mit der Endung ".php" enden, mit Ausnahme der View Skripte. Die folgenden Beispiele zeigen akzeptierbare Dateinamen für Zend Framework Klassen: Zend/Db.php Zend/Controller/Front.php Zend/View/Helper/FormRadio.php Dateinamen müssen den Klassennamen wie oben beschrieben entsprechen. B.3.3. Funktionen und Methoden Funktionsnamen dürfen nur Alphanummerische Zeichen enthalten. Unterstriche sind nicht gestattet.
Nummern sind in Funktionsnamen gestattet aber in den meisten Fällen nicht empfohlen. Funktionsnamen müssen immer mit einem Kleinbuchstaben anfangen. Wenn Funktionsnamen aus mehr als einem Wort bestehen, muß der erste Buchstabe jeden Wortes großgeschrieben werden. Das wird normalerweise "camelcase" Formatierung genannt. Wortreichtum wird generell befürwortet. Funktionsnamen sollten so wortreich wie möglich sein um deren Zweck und Verhalten zu erklären. Das sind Beispiele akzeptierbarer Namen für Funktionen: filterinput() getelementbyid() widgetfactory() Für objekt-orientiertes Programmieren, sollten Zugriffspunkte für Instanzen oder statische Variablen immer mit "get" oder "set" beginnen. Wenn Design-Pattern implementiert werden, wie Singleton oder das Factory Pattern, sollte der Name der Methode den Namen des Pattern enthalten wo es praktikabel ist, um das Verhalten besser zu beschreiben. Für Methoden in Objekten die mit dem "private" oder "protected" Modifikator deklariert sind, muß das erste Zeichen des Namens der Methode ein einzelner Unterstrich sein. Das ist die einzige akzeptable Anwendung von einem Unterstrich im Namen einer Methode. Methoden die als "public" deklariert sind sollten nie einem Unterstrich enthalten. Funktionen im globalen Bereich (auch "floating functions" genannt) sind gestattet aber es wird von Ihnen in den meisten Fällen abgeraten. Diese Funktionen sollten in einer statischen Klasse gewrappt werden. B.3.4. Variablen Variablennamen dürfen nur Alphanummerische Zeichen enthalten. Unterstriche sind nicht gestattet. Nummern sind in Variablen gestattet in den meisten Fällen aber nicht empfohlen. Für Instanzvariablen die mit dem "private" oder "protected" Modifikator deklariert werden, muß das erste Zeichen des Funktionsnamens ein einzelner Unterstrich sein. Das ist die einzige akzeptierte Anwendung eines Unterstriches in einem variablen Namen. Klassenvariablen welche als "public" deklariert werden sollten nie mit einem Unterstrich beginnen. Wie bei Funktionsnamen (siehe Abschnitt 3.3) müssen Variablennamen immer mit einem Kleinbuchstaben starten und der "camelcaps" Schreibweise folgen. Wortreichtum wird generell befürwortet. Variablen sollen immer so wortreich wie möglich sein um die Daten zu beschreiben die der Entwickler in Ihnen zu speichern gedenkt. Von gedrängte Variablennamen wie "$i" und "$n" wird abgeraten für alles außer die kleinsten Schleifen. Wenn eine Schleife mehr als 20 Codezeilen enthält sollten die Index-Variablen einen ausführlicheren Namen haben. B.3.5. Konstanten Konstanten können beides enthalten, sowohl Alphanummerische Zeichen als auch Unterstriche. Nummern sind in Konstantennamen gestattet. Alle Buchstaben die in Konstantenname verwendet werden müssen großgeschrieben haben, wärend Wörter in einem Konstantennamen durch Unterstriche getrennt werden müssen. Zum Beispiel ist EMBED_SUPPRESS_EMBED_EXCEPTION gestattet aber EMBED_SUPPRESSEMBEDEXCEPTION nicht.
Konstanten müssen als Klassenkonstanten definiert werden mit dem "const" Modifikator. Die Definition von Konstanten im globalen Bereich mit der "define" Funktion ist gestattet aber es wird es wird stärkstens davon abgeraten. B.4. Code Stil B.4.1. PHP Code Abgrenzung PHP Code muß immer mit der kompletten Form des Standard-PHP Tags abgegrenzt sein: <?php?> Kurze Tags sind nie erlaubt. Für Dateien die nur PHP Code enthalten, darf das schließende Tag nie angegeben werden (Siehe Abschnitt B.2.1, Allgemein ). B.4.2. Strings B.4.2.1. String Literale Wenn ein String ein Literal ist (er also keine Variablenvertreter enthält), sollte immer das Apostroph oder "einzelne Anführungszeichen" verwendet werden um den String abzugrenzen: $a = 'Beispiel String'; B.4.2.2. String Literale die Apostrophe enthalten Wenn ein literaler String selbst Apostrophe enthält, ist es gestattet den String mit Anführungszeichen oder "doppeltes Anführungszeichen" abzugrenzen. Das ist speziell für SQL Anweisungen nützlich: $sql = "SELECT `id`, `name` from `people` ". "WHERE `name`='fred' OR `name`='susan'"; Diese Syntax ist zu bevorzugen, im Gegensatz zum Ausbruch von Apostrophs, da Sie viel einfacher lesbar ist. B.4.2.3. Variabler Austausch Variabler Austausch ist gestatten bei Verwendung einer der Formen: $greeting = "Halle $name, willkommen zurück!"; $greeting = "Hallo $name, willkommen zurück!"; Aus Gründen der Konstistenz ist folgende Form nicht gestattet: $greeting = "Hallo $name, willkommen zurück!";
B.4.2.4. Verbinden von Strings Strings müssen verbunden werden indem man den "." Operator verwendet. Ein Leerzeichen muß immer vor und nach dem "." Operator hinzugefügt werden um die Lesbarkeit zu erhöhen: $company = 'Zend'. ' '. 'Technologies'; Wenn Strings mit dem "." Operator verbunden werden, ist es empfohlen die Anweisung in mehrere Zeilen umzubrechen um die Lesbarkeit zu erhöhen. In diesen Fällen sollte jede folgende Zeile mit Leerraum aufgefüllt werden so das der "." Operator genau unterhalb des "=" Operators ist: $sql = "SELECT `id`, `name` FROM `people` ". "WHERE `name` = 'Susan' ". "ORDER BY `name` ASC "; B.4.3. Arrays B.4.3.1. Nummerisch indizierte Arrays Negative Nummern sind in Indezes nicht gestattet. Ein indiziertes Array kann mit mit irgendeiner nicht-negativen Nummer beginnen, trotzdem sind alle BasisIndex neben 0 nicht erlaubt. Wenn indizierte Arrays mit dem array Funktion deklariert werden, muß ein folgendes Leerzeichen nach jeder Kommabegrenzung hinzugefügt werden um die Lesbarkeit zu erhöhen: $samplearray = array(1, 2, 3, 'Zend', 'Studio'); Es ist gestattet mehrzeilige indizierte Arrays zu definieren bei Verwendung des "array" Konstrukts. In diesem Fall, muß jede folgende Zeile mit Leerzeichen aufgefüllt werden so das der Beginn jeder Zeile ausgerichtet ist: $samplearray = array(1, 2, 3, 'Zend', 'Studio', $a, $b, $c, 56.44, $d, 500); B.4.3.2. Assoziative Arrays Wenn assoziative Arrays mit dem array Konstrukt deklariert werden, ist das Umbrechen der Anweisung in mehrere Zeilen gestattet. In diesem Fall muß jede folgende Linie mit Leerraum aufgefüllt werden so das beide, der Schlüssel und der Wert untereinander stehen: $samplearray = array('firstkey' => 'firstvalue', 'secondkey' => 'secondvalue'); B.4.4. Klassen B.4.4.1. Klassen Deklarationen Klassen müssen entsprechend der Zend Framework Namenskonvention benannt werden. Die Klammer sollte immer in der Zeile unter dem Klassennamen geschrieben werden.
Jede Klasse muß einen Dokumentationsblock haben der dem PHPDocumentor Standard entspricht. Jeder Code in der Klasse muß mit vier Leerzeichen eingerückt sein. Nur eine Klasse ist in jeder PHP Datei gestattet. Das Platzieren von zusätzlichem Code in Klassendateien ist gestattet aber es wird davon abgeraten. In solchen Dateien müssen zwei leere Zeilen die Klasse von jedem zusätzlichen PHP Code in der Datei seperieren. Das folgende ist ein Beispiel einer akzeptierbaren Klassendeklaration: class SampleClass // gesamter Inhalt der Klasse // muss mit vier Leerzeichen eingerückt sein B.4.4.2. Klassenvariablen Klassenvariablen müssen entsprechend den Variablen-Benennungs-Konventionen des Zend Frameworks benannt werden. Jede Variable die in der Klasse deklariert wird muß am Beginn der Klasse ausgelistet werden, vor der Deklaration von allen Methoden. Das var Konstrukt ist nicht gestattet. Klassenvariablen definieren Ihre Sichtbarkeit durch die Verwendung des private, protected, oder public Modifikatoren. Das gestatten von direktem Zugriff auf Klassenvariablen durch deren Deklaration als public ist gestattet aber es wird davon abgeraten da hierfür Zugriffsmethoden verwendet werden sollten (set/get). B.4.5. Funktionen und Methoden B.4.5.1. Deklaration von Funktionen und Methoden Funktionen müssen nach der Funktions-Namenskonvention des Zend Frameworks benannt werden. Methoden innerhalb von Klassen müssen immer Ihre Sichtbarkeit durch Verwendung einer der private, protected, oder public Modifikatoren definieren. Wie bei Klassen, sollte die Klammer immer in der Zeile unterhalb des Funktionsnamens geschrieben werden. Leerzeichen zwischen dem Funktionsnamen und der öffnenden Klammer für die Argumente sind nicht erlaubt. Von Funktionen im globalen Raum wird komplett abgeraten. Das folgende ist ein Beispiel einer akzeptierbaren Funktionsdeklaration in einer Klasse: class Foo public function bar()
// gesamter Inhalt der Funktion // muss durch view Leerzeichen eingerückt sein NOTIZ: Die Übergabe per Referenz ist die einzige erlaubt Mechanismus für die Übergabe von Parametern in der Deklaration einer Funktion: class Foo public function bar(&$baz) Der Aufruf durch Referenz ist nicht gestattet. Der Rückgabewert darf nicht in Klammern stehen. Das kann die Lesbarkeit behindern und zusätzlich den Code unterbrechen wenn eine Methode später auf Rückgabe durch Referenz geändert wird. class Foo * FALSCH public function bar() return($this->bar); * RICHTIG public function bar() return $this->bar; B.4.5.2. Verwendung von Funktionen und Methoden Funktionsargumente sollten durch ein einzelnes trennendes Leerzeichen nach dem Komma Trennzeichen getrennt werden. Das folgende ist ein Beispiel für einen akzeptierbaren Aufruf einer Funktion die drei Argumente benötigt: threearguments(1, 2, 3); Übergabe von Referenzen zur Laufzeit ist strengstens verboten. Siehe die Sektion für Funktions Deklarationen für den richtigen Weg um Funktionsargumente per Referenz zu übergeben.
Durch die Übergabe von Arrays als Argument für eine Funktion, kann der Funktionsaufruf den "array" Hinweis enthalten und kann in mehrere Zeilen geteilt werden um die Lesbarkeit zu erhöhen. In solchen Fällen sind die normalen Richtlinien für das Schreiben von Arrays trotzdem noch anzuwenden: threearguments(array(1, 2, 3), 2, 3); threearguments(array(1, 2, 3, 'Zend', 'Studio', $a, $b, $c, 56.44, $d, 500), 2, 3); B.4.6. Kontrollanweisungen B.4.6.1. If/Else/Elseif Kontrollanweisungen die auf den if und elseif Konstrukten beruhen müssen ein einzelnes Leerzeichen vor der öffnenden Klammer der bedingten Anweisung und ein einzelnes Leerzeichen nach der schließenden Klammer. Innerhalb der bedingten Anweisungen zwischen den Klammern, müssen die Operationen, für die Lesbarkeit, durch Leerzeichen getrennt werden. Innere Klammern sind zu befürworten um die logische Gruppierung für größeren bedingte Anweisungen zu erhöhen. Die öffnende Klammer wird in der selben Zeile geschrieben wie die Bedingungsanweisung. Die schließende Klammer wird immer in einer eigenen Zeile geschrieben. Jeder Inhalt innerhalb der Klammer muß durch Verwendung von vier Leerzeichen eingerückt werden. if ($a!= 2) $a = 2; Für "if" Anweisungen die "elseif" oder "else" beinhalten, sind die Konventionen der Formatierung ähnlich dem "if" Konstrukt. Das folgende Beispiel zeigt gültige Formatierungen für "if" Anweisungen mit "else" und/oder "elseif" Konstrukten: if ($a!= 2) $a = 2; else $a = 7; if ($a!= 2) $a = 2; elseif ($a == 3) $a = 4; else $a = 7; PHP erlaubt das Anweisungen in einigen Fällen auch ohne Klammern zu schreiben. Dieser Coding Standard macht keine Unterscheidungen und es müssen alle "if", "elseif" oder "else" Anweisungen in Klammern geschrieben werden. Die Verwendung des "elseif" Konstruktes ist erlaubt es wird aber strengstens davon abgeraten und es ist die "else if" Kombination zu bevorzugen.
B.4.6.2. Switch Kontrollanweisungen die mit der "switch" Anweisung geschrieben werden müssen ein einzelnes Leerzeichen vor der öffnenden Klammer der Bedingten Anweisung besitzen, und auch nach der schließenden Klammer. Jeglicher Inhalt innerhalb der "switch" Anweisung muß durch Verwendung von vier Leerzeichen eingerückt sein. Der Inhalt unter jeder "case" Anweisung muß durch Verwendung von vier zusätzlichen Leerzeichen eingerückt werden. switch ($numpeople) case 1: break; case 2: break; default: break; Das default Konstrukt darf nie bei der switch Anweisung vergessen werden. NOTIZ: Es ist machmal nützlich eine case Anweisung zu schreiben, die durch das nächste case fällt indem innerhalb solcher Fälle kein break oder return angegeben wird. Um diese Fälle von Fehlern zu unterscheiden, sollte jede case Anweisung in der break oder return unterlassen werden einen Kommentar enthalten der anzeigt das das break gewünschtermaßen unterdrückt wurde. B.4.7. Inline Dokumentation B.4.7.1. Dokumentations Format Alle Dokumentations Blöcke ("DocBlock") müssel mit dem phpdocumentor Format kompatibel sein. Die Beschreibung des phpdocumentor Formats is jenseits der Reichweite dieses Dokuments. Für weiterführende Informationen siehe: http://phpdoc.org"> Alle Klassen Dateien müssen einen "file-level" Docblock am Beginn jeder Datei und einen "classlevel" Docblock direkt überhalb jeder Klasse enthalten. Beispiele solcher Docblocks können anbei gefunden werden. B.4.7.2. Dateien Jede Datei die PHP Code enthält muß einen Docblock am Beginn der Datei besitzen welcher mindestens diese phpdocumentor Tags enthält: * Kurze Beschreibung der Datei * * Lange Beschreibung der Datei (wenn vorhanden)... * * LICENSE: Einige Lizenz Informationen * * @copyright 2008 Zend Technologies * @license http://framework.zend.com/license BSD License * @version $Id:$ * @link http://framework.zend.com/package/packagename * @since Datei vorhanden seit Release 1.2.0
B.4.7.3. Klassen Jede Klasse muß einen Docblock haben welche mindestens diese phpdocumentor Tags enthält: * Kurze Beschreibung für die Klasse * * Lange Beschreibung für die Klasse (wenn vorhanden)... * * @copyright 2008 Zend Technologies * @license http://framework.zend.com/license BSD License * @version Release: @package_version@ * @link http://framework.zend.com/package/packagename * @since Klasse vorhanden seit Release 1.5.0 * @deprecated Klasse abgeraten ab Release 2.0.0 B.4.7.4. Funktionen Jede Funktion, auch Objekt Methoden, müssen einen Docblock haben welcher mindestens folgendes enthält: Eine Beschreibung der Funktion Alle Argumente Alle möglichen Rückgabewerte Es ist nicht notwendig das "@access" Tag zu verwenden, weil das Accesslevel bereits vom "public", "private" oder "protected" Modifikator bekannt ist wenn die Funktion deklariert wird. Wenn eine Funktion/Methode eine Ausnahme werfen könnte, muß @throws für alle bekannten Exception Klassen verwendet werden: @throws exceptionclass [Beschreibung]