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. 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 Zend Framework 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 Zend Framework Coding Standard abgedeckt werden enthalten: PHP Dateiformatierung Namens Konventionen Code Stil Inline Dokumentation Coding Standards sind in jedem Entwicklungs Projekt wichtig, aber sie sind 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. 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. Ein Einzug sollte aus 4 Leerzeichen bestehen. Tabulatoren sind nicht erlaubt. 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 PHP Codezeile beträgt 120 Zeichen. 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). 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 Zend Framework Standard Bibliothek ist das "Zend/" Verzeichnis, wobei das Basisverzeichnis der Zend Framework 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. Generell folgen abstrakte Klassen der gleichen Konvention wie Klasses, mit einer zusätzlichen Regel: Die Namen von abstrakten Klassen müssen mit derm Term "Abstract" enden, und dem Term darf kein Unterstrich vorangestellt sein. Als Beispiel wird Zend_Controller_Plugin_Abstract als ungültig angenommen, aber Zend_Controller_PluginAbstract oder Zend_Controller_Plugin_PluginAbstract wären gültige Namen. Diese Namens Konvention ist neu mit Version 1.9.0 des Zend Frameworks. Bei Klassen vor dieser Version kann es sein das sie dieser Regel nicht folgen, aber Sie werden in Zukunft umbenannt um zu entsprechen. Generell folgen Interfaces der gleichen Konvention wie Klasses, mit einer zusätzlichen Regel: Die Namen von Interfaces können optional mit dem Term "Interface" enden, aber dem Term darf kein Unterstrich vorangestellt sein. Als Beispiel wird Zend_Controller_Plugin_Interface als ungültig angenommen, aber Zend_Controller_PluginInterface oder Zend_Controller_Plugin_PluginInterface wären gültige Namen. Wärend diese Regel nicht benötigt wird, wird Sie stark empfohlen, da Sie Entwicklern einen guten visuellen Hinweis gibt welche Dateien ein Interface enthalten und welche Klassen. Diese Namens Konvention ist neu mit Version 1.9.0 des Zend Frameworks. Bei Klassen vor dieser Version kann es sein das sie dieser Regel nicht folgen, aber Sie werden in Zukunft umbenannt um zu entsprechen. 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: Dateinamen müssen den Klassennamen wie oben beschrieben entsprechen. 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: 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. 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. 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. PHP Code muß immer mit der kompletten Form des Standard-PHP Tags abgegrenzt sein: ]]> Kurze Tags sind nie erlaubt. Für Dateien die nur PHP Code enthalten, darf das schließende Tag nie angegeben werden (Siehe ). 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: 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: Diese Syntax ist zu bevorzugen, im Gegensatz zum Ausbruch von Apostrophs, da Sie viel einfacher lesbar ist. Variabler Austausch ist gestatten bei Verwendung einer der Formen: Aus Gründen der Konstistenz ist folgende Form nicht gestattet: 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: 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: 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: 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: Alternativ kann das beginnende Array Element in der folgenden Zeile beginnen. Wenn das so ist, sollte es um ein Einrückungslevel tiefer stehen als die Zeile welche die Array Deklaration enthält und alle folgenden Zeilen sollten die gleiche Einrückung haben; der schließende Teil sollte in einer eigenen Zeile stehen und das gleiche Einrückungslevel haben wie die Zeile welche die Array Deklaration enthält: Wenn die letztere Deklaration verwendet wird, empfehlen wir ein endendes Komma für das letzte Element im Array zu verwenden; das minimiert das Problem beim Hinzufügen von neuen Elements bei zusätzlichen Zeilen, und hilft sicherzustellen das durch ein fehlendes Komma keine Parsing Fehler auftreten. 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: 'firstValue', 'secondKey' => 'secondValue'); ]]> Alternativ kann das beginnende Array Element in der folgenden Zeile beginnen. Wenn das so ist, sollte es um ein Einrückungslevel tiefer stehen als die Zeile welche die Array Deklaration enthält und alle folgenden Zeilen sollten die gleiche Einrückung haben; der schließende Teil sollte in einer eigenen Zeile stehen und das gleiche Einrückungslevel haben wie die Zeile welche die Array Deklaration enthält. Wegen der Lesbarkeit sollten die verschiedenen "=>" Operatoren so eingerückt werden das Sie untereinander stehen. 'firstValue', 'secondKey' => 'secondValue', ); ]]> Wenn die letztere Deklaration verwendet wird, empfehlen wir ein endendes Komma für das letzte Element im Array zu verwenden; das minimiert das Problem beim Hinzufügen von neuen Elements bei zusätzlichen Zeilen, und hilft sicherzustellen das durch ein fehlendes Komma keine Parsing Fehler auftreten. 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: Klassen die andere Klassen erweitern oder welche Interfaces implementieren sollen Ihre Abhängigkeit auf der gleichen Zeile deklarieren wenn das möglich ist. Wenn als Ergebnis so einer Deklaration, die Länge der Zeile die Maximale Zeilenlänge überschreitet, ist die Zeile vor dem "extends" und oder "implements" Schlüsselwort umzubrechen und diese Zeilen um ein Einrückungslevel einzurücken. Wenn die Klasse mehrere Interfaces implementiert und die Deklaration die maximale Zeilenlänge übersteigt, ist nach jedem Komma umzubrechen und die Interfaces zu separieren, und die Namen des Interfaces so einzurücken das Sie untereinander stehen. 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). 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: In den Fällen wo die Liste der Argumente die maximale Zeilenlänge überschreitet, sollten Zeilenumbrüche eingeführt werden. Zusätzliche Argumente der Funktion oder Methode müssen durch einen zusätzlichen Einrückungslevel nach der Funktion oder Methodendeklaration eingerückt werden. Ein Zeilenumbruch sollte dann vor dem schließenden Argument stattfinden, welcher in der gleichen Zeile platziert werden sollte wie die öffnende Klammer der Funktion oder Methode mit einem einzelnen Leerzeichen das die zwei trennt, und mit dem gleichen Einrückungslevel wie die Deklaration der Funktion oder Methode. Das folgende ist ein Beispiel so einer Situation: Notiz: Die Übergabe per Referenz ist die einzige erlaubt Mechanismus für die Übergabe von Parametern in der Deklaration einer Funktion: 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. bar); } /** * RICHTIG */ public function bar() { return $this->bar; } } ]]> 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: Ü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: 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. Wenn die Kontrollanweisung die Ursache für eine Überschreitung der maximalen Zeilenlänge ist, und sie mehrere Anweisungen hat, kann die Kontrollanweisung in mehrere Zeilen gebrochen werden. In solchen Fällen, ist die Zeile vor dem logischen Operator zu brechen und die Zeile so einzurücken das Sie unter dem ersten Zeichen der Kontrollanweisung steht. Der schließende Teil der Kontrollanweisung ist mit der öffnenden Klammer in einer eigenen Zeile zu platzieren, wobei ein einzelnes Leerzeichen die zwei trennen muß, und der Einrückungslevel identisch mit der öffenden Kontrollanweisung sein ist. Die Einrückung des späteren Deklarationsformats dient der Vorbeugung von Problemen beim Hinzufügen oder entfernen von Klauseln von der Kontrollanweisung bei späteren Revisionen. 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: 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. 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. 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. 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 "class-level" Docblock direkt überhalb jeder Klasse enthalten. Beispiele solcher Docblocks können anbei gefunden werden. Jede Datei die PHP Code enthält muß einen Docblock am Beginn der Datei besitzen welcher mindestens diese phpDocumentor Tags enthält: Das @category Tag muß den Wert "Zend" haben. Das @package Tag muß hinzugefügt sein, und sollte mit dem Namen der Komponente identisch sein dessen Klasse in der Datei enthalten ist; typischerweise wird dieser zwei Segmente haben, den Präfix "Zend", und den Namen der Komponente. Das @subpackage Tag ist optional. Wenn es angegeben wird, sollte es der Name der Subkomponente sein, ohne den Präfix der Klasse. Im obigen Beispiel ist die Annahme das die Klasse in der Datei entweder "Zend_Magic_Wand" ist oder den Klassennamen als Teil seines Präfixes verwendet. Jede Klasse muß einen Docblock haben welche mindestens diese phpDocumentor Tags enthält: Das @category Tag muß den Wert "Zend" haben. Das @package Tag muß hinzugefügt sein, und sollte mit der Komponente identisch sein der die Klasse gehört; typischerweise wird dieser zwei Segmente haben, den Präfix "Zend", und den Namen der Komponente. Das @subpackage Tag ist optional. Wenn es angegeben wird, sollte es der Name der Subkomponente sein, ohne den Präfix der Klasse. Im obigen Beispiel ist die Annahme das die Klasse in der Datei entweder "Zend_Magic_Wand" ist oder den Klassennamen als Teil seines Präfixes verwendet. 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 oder Methode eine Ausnahme werfen könnte, muß @throws für alle bekannten Exception Klassen verwendet werden: