PEAR Coding Standard

Coding Style Index?

1.  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.

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

Bsp für if-Kosntruktionen:

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:

3.  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:

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:

4.  Klassen-Definition

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

5.  Funktionsdefinitionen

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

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:

6.  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.

7.  Code einbinden

Immer wenn Sie eine Klassendatei unbedingt inkludieren müssen, dann benutzen Sie require_once. Benötigen Sie hingegen eine Datei nur bedingt, z.B. in Factory-Methoden, verwenden Sie include_once. 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.

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

8.  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.

9.  Kopf-Kommentare

Alle Quellcode-Dateien sollen einen „Page-level“ Docblock am Datei-Anfang besitzen und einen „Class-level“ Docblock unmittelbar vor jeder Klasse.

Beispiele:

9.1  Erforderliche Tags

Kurzbeschriebung

Die Kurzbeschreibung muss in allen Docblocks existieren. Sie umfasst einen Satz, und sollten keinesfalls nur aus dem Namen des beschreibenden Objektes stehen.

PHP Version

Folgende Zeile muss in den Page-level-Docblock eingefügt werden. Sie beschreibt, unter welcher PHP-Version der Quellcode läuft:

• PHP version 4
• PHP version 5
• PHP versions 4 and 5

@license

Sie können verschiedene Lizenzen für ihr Package verwenden. Sie müssen eine auswählen und diese sowohl im Page-level-, wie auch dem Class-level-Docblock einfügen:

• @license http://www.apache.org/licenses/LICENSE-2.0 Apache License 2.0
• @license http://www.freebsd.org/copyright/freebsd-license.html BSD License (2 Clause)
• @license http://www.debian.org/misc/bsd.license BSD License (3 Clause)
• @license http://www.freebsd.org/copyright/license.html BSD License (4 Clause)
• @license http://www.opensource.org/licenses/mit-license.html MIT License
• @license http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
• @license http://www.php.net/license/3_0.txt PHP License 3.0

@link

Die Link-Angabe muss im Page-level- and Class-level-Docblock erfolgen. Sie müssen den Eintrag für „PackageName“ natürlich durch den Namen Ihres Packages ersetzen. Auf diese Weise ist sicher gestellt, dass die API-Dokumentation die Links auf die Package-Homepage enthält.

• @link http://pear.php.net/package/PackageName

@author

Es gibt keine klare Regel, wann jemand zur Liste der Quellcode-Autoren hinzugefügt werden sollte. Allgemein sollten sie substanziell beigetragen haben, ca. 10% bis 20% des Codes. Sie können Ausnahmen machen, wenn Methoden neu geschrieben wurden oder neue Logik beigesteuert wurde.

Einfache Code-Neuformatierungen oder Bug-Fixes sollten nicht zur Aufnahme in die Liste führen.

@since

Dieses Tag ist erforderlich, wenn eine Datei oder Klasse nach dem ersten Release zum Package ergänzt wurde. Verwenden Sie es nicht beim ersten Release.

@deprecated

Dieses Tag ist erforderlich, wenn eine Datei oder Klasse nicht mehr benutzt wird, aber für die Rückwärtskompatibilität noch verfügbar ist.

9.2  Optionale Tags

@copyright

Sie können dieses Tag setzen, wenn Sie Copyright-Anmerkungen ergänzen wollen. Das Format des Tags: Die vierstellige Jahreszahl bzw. bei mehreren Jahren, nur das erste und letzte Jahr getrennt mit einem Querstrich; danach der Copyright-Inhaber, also die betreffenden Personen, Firma oder z.B. die PHP Group.

Beispiele:

• @copyright 2003 John Doe and Jennifer Buck
• @copyright 2001-2004 John Doe
• @copyright 1997-2004 The PHP Group
• @copyright 2001-2004 XYZ Corporation

License Summary

If you are using the PHP License, use the summary text provided above. If another license is being used, please remove the PHP License summary. Feel free to substitute it with text appropriate to your license, though to keep things easy to locate, please preface the text with LICENSE: .

@see

Fügen Sie ein @see-Tag hinzu, wenn Sie auf andere Abschnitte in der Package-Dokumentation verweisen. Wenn Sie mehrere Einträge hinzufügen, verwenden Sie nicht mehrere Tags, sondern trennen diese in einem Tag per Komma.

Abfolge und Leerzeichen

Um die langfristige Lesbarkeit zu gewährleisten, sollten Texte und Tags dem gegebenem Beispiel folgen. Diese Festlegungen entsprechen dem JavaDoc-Standard.

Verwendung von @package_version@

Es gibt zwei Wege @package_version@ zu ersetzen. Das ist abhängig davon, ob Sie die Package-Datei package.xml von Hand erzeugen oder das Package PackageFileManager benutzen.

Wenn Sie die Datei direkt bearbeiten, ergänzen Sie ein <replace>-Tag für jede Datei. Das XML sieht dann ähnlich wie dieses aus:

Wenn PackageFileManager verwenden, rufen Sie addReplacement() für jede Datei auf:

9.3  Übergangsregeln

Für existierende kleine Packages

Existierende Packages mit nur wenigen Dateien sollten die DocBlöcke im nächst möglichen Release enthalten.

Für existierende große Packages

Existierende Packages mit vielen Dateien sollten die neuen DocBlöcke sobald wie möglich integrieren. Auf jeden Fall aber mit den nächsten Major-Release.

Neue und unveröffentliche Packages

Neue Packages und existierende Package, für welche noch kein Release existiert, müssen über die DocBlöcke verfügen, wenn ihr erstes Release erscheint.

10.  CVS-Nutzung

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

11.  Beispiel-URLs

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

12.  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()

12.1  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.

12.2  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.

13.  Dateiformate

Alle Skripte in PEAR müssen:

• als ASCII gespeichert werden.
• mit dem Zeichensatz ISO-8859-1 kodiert werden.
• den UNIX-Konventionen folgen. „Unix-Konventionen“ bedeutet:
  • Zeilen dürfen nur mit dem Line-Feed-Zeichen (LF) enden. Das Zeichen entspricht dem Ordinal-Wert 10, Octal 012 und hexadezimal 0A. Benutzen Sie kein Carriage-Return-Zeichen (CR) wie unter Apple Macintosh-Computern oder die CRLF-Kombination unter Windows.
  • Fügen Sie ein Zeilenende-Zeichen nach dem schliessendem PHP-Tag (?>) ein. Das bedeutet, der Cursor im Editor steht eine Zeile nach dem schliessendem Tag.

14.  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. Erst wenn eine neue major-Version eines Packages erscheint, dann muss diese Version der E_STRICT-Konvention entsprechen.

15.  Richtlinen zur Fehlerbehandlung

15.1  Richtlinen zur Fehlerbehandlung

Dieser Abschnitt beschreibt wie Fehler in PEAR-Packages behandelt werden sollen, die für PHP 5 und 6 entwickelt werden. Fehler werden über Exceptions abgewickelt, sie wurden mit PHP 5.0 und der Zend Engine 2 eingeführt.

Was ist ein Fehler?

Ein Fehler ist definiert als ein unerwartet, nicht korrekter Programmzustande, der nicht wieder behoben werden kann. Zur Vereinfachung dieser Definition gilt, dass die Behebung des Fehlers nicht innerhalb einer Methode möglich ist. Eine unvollständige Behebung gilt trotzdem als Behebung.

Beispiel 4-1. Eine typische Fehlersituation

In diesem Beispiel soll die Methode die Verbindung mit der Datenbank mit dem gegegebenem DSN herstellen. Die Methode ruft ihrerseits nur PEAR::DB, wenn dieses Package einen Fehler wirft, kann nur eine Exception erzeugt und geworfen werden, ohne weiter Einfluß nehmen zu können.

Beispiel 4-2. Fehlerbehandlung mit Behebung

Das zweite Beispiel zeigt, wie eine Exception empfangen und behandelt wird. Die verwendete connectDB()-Methode kann nur einen Fehler melden, wenn die Verbindung fehlschlägt. Die übergeordnete Methode connect() hingegen weiss, dass das Objekt auch mit einer der anderen Datenbank-Verbindungen lauffähig ist. Deshalb kann der Fehler als behoben angesehen werden und die Exception wird nicht weitergeleitet.

Beispiel 4-3. Unvollständige Behebung

Die Fehlerbehebung führt zu Seiteneffekten, deshalb ist sie nicht vollständig. Das Programm kann weiterlaufen, die Exception gilt als behandelt und muss nicht weitergeleitet werden. Wie im vorherigen Beispiel sollte die aufgetretene Exception aber trotzdem geloggt werden oder eine andere Form der Warnung stattfinden.

Fehler-Benachrichtigung PHP 5 PEAR-Packages

Fehlerhafte Zustände in PEAR-Packages für PHP 5 müssen über Exceptions gemeldet werden. Nicht mehr verwendet werden sollten Fehlercodes oder ein PEAR_Error-Objekt. Diese Regel gilt natürlich nicht, wenn das Package kompatibel mit PHP 4 bleiben muss. In diesem Fall gelten die Konvention der PEAR Coding Standards unter PHP 4 weiter.

Eine Exception sollte immer geworfen werden, wenn ein fehlerhafter Zustand auftritt, entsprechend der Definition im vorherigen Abschnitt. Die geworfene Exception sollte genügend Informationen enthalten, um den Fehler debuggen zu können und schnell dessen Grund herauszufinden. Bedenken Sie, dass in Produktionsumgebungen keine Exception an den Endanwender durchdringen sollten. Deshalb muss man sich keine Gedanken machen über die Komplexität der Fehlermeldung.

Die Basis-Klasse PEAR_Exception enthält eine wörtliche Beschreibung des Fehlers, womit der Programmzustand beschrieben wird, der zum Fehler führte, und - optional - Execptions, die durch untergeordnete Programmaufrufe herbei geführten wurden und die ursprüngliche Ursache des Fehlers darstellen können.

Die Arten von Informationen die in einer Exception enthalten sein müssen, hängt von der Art des Fehlers ab. Es gibt drei Varianten von Exceptions:

1. Fehler, die während der Vorabprüfung auftreten können.
2. Fehler, die durch untergeordneten Bibliotheksaufrufe auftreten und durch Fehlercodes oder -Objekte signalisiert werden
3. Nicht-korrigierbare Exceptions von untergeordneten Bibliotheken.

Fehler, die während der Vorabprüfung auftreten können, sollten eine Beschreibung der fehlgeschlagenen Prüfung enthalten. Wenn möglich sollte der fehlerhafte Wert mit angegeben werden.

Beispiel 4-4.

Fehler, die durch untergeordneten Bibliotheksaufrufe auftreten und durch Fehlercodes oder -Objekte signalisiert werden, sollten in Exceptions umgewandelt werden, wenn diese nicht behoben werden können. Die Fehlerbeschreibung sollte die originale Fehlerinformationen enthalten bzw. entsprechend konvertiert werden. Am Beispiel der obigen connect()-Methode:

Beispiel 4-5.

Nicht-korrigierbare Exceptions von untergeordneten Bibliotheken sollten weitergeleitet oder erneut geworfen werden. Wenn sie weitergeleitet werden soll, dann behandeln Sie die Exception nicht weiter. Wenn Sie die Exception erneut werfen, dann müssen Sie die originale Exception in der neuen Exception verpacken.

Beispiel 4-6. Eine Exception neu verpacken

Beispiel 4-7. Eine Exception weiterleiten

Die Entscheidung, ob eine Exception neu verpackt oder weitergeleitet werden soll, ist eine Frage der Software-Architektur. Exceptions sollten weitergeleitet werden, ausser in zwei Fällen:

1. Die originale Excpetion ist von einem anderen Package. Wenn diese weitergeleitet wird, dann würden Details der Implementierung nach aussen dringen.
2. Die Methode kann nützliche Debug-Informationen ergänzen.

15.2  Exceptions und der normale Programmfluß

Exceptions sollten niemals als Bestandteil des normalen Programmflußes benutzt werden. Wenn alle Logik zur Behandlung von Exceptions entfernt würde (try-catch-Statements), dann sollte der verbliebende Code den "wahren Pfad" repräsentieren -- dem Programmfluß, wenn keinerlei Fehler auftreten würden.

Diese Forderung entspricht der Erwartung, dass Exceptions nur bei fehlerhaften Zuständen geworfen werden sollten und niemals bei regulären Zuständen.

Ein Beispiel für die falsche Benutzung der Exception-Weiterleitung ist die Rückgabe eines Wertes eines rekursiven Aufrufs:

Beispiel 4-8.

Im Beispiel wird die ResultException benutzt, um "schnell" wieder aus der Rekursion heraus zu kommen. Das ist im Fehlerfall tatsächlich praktisch, in diesem Fall, aber nur ein Beispiel für einen faulen Programmierer. Die Klassen-Hierarchie von Exceptions

Alle Exceptions, die von Packages geworfen werden, müssen von PEAR_Exception abstammen. PEAR_Exception bietet zusätzliche Fähigkeiten, um andere Exceptions zu verpacken. Sie finden diese nicht in der obersten PHP Exception-Klasse, sind aber notwendig, um die oben gestellten Anforderungen zu erfüllen.

Zusätzlich sollte jedes PEAR-Package seine eigene Exception-Klasse definieren; der Name der Klasse entspricht dem Muster: <Package_Name>_Exception. Jede Exception sollte von dieser Klasse abgeleitet werden. Exceptions dokumentieren

Da PHP, im Gegensatz zu Java, es nicht erfordert, mögliche Exceptions in der Funktionssignatur aufzunehmen, ist deren sorgfältige Dokumentation im Methodenkopf wichtig.

Beispiel 4-9. Exceptions werden dokumentiert mit dem @throws-Schlüsselwort

In vielen Fällen wandelt die mittlere Schicht einer Anwendung Exceptions von untergeordneten Methoden in aussagekräftiger, anwendungsspezifische Exceptions. Das sollte ebenfalls angesprochen werden:

Beispiel 4-10.

In anderen Fällen kann ihre Methode als Filter fungieren, der nur bestimmte Exceptions weiterleitet. Dann sollten Sie dokumentieren, welche Exceptions nicht von Ihrer Methode abgefangen werden.

Beispiel 4-11.

15.3  Exceptions als Teil der API

Exceptions spielen eine kritische Rolle in der API ihrer Bibliothek. Entwickler, die Ihre Bibliothek verwenden, sind abhängig von der angemessenen Beschreibung wo und warum Exceptions auftreten in Ihrem Package. Auch die sorgfältige Planung der Fehlermeldungen ist ein wichtiger Faktor für die Erhaltung der Rückwärts-Kompatibilität.

Da Exceptions ein integraler Bestandteil der API ihres Packages sind, darf bei Änderungen daran die Rückwärts-Kompatibilität (BC) nicht grundlos gebrochen werden.

Dinge, die zum Bruch führen:

• Jede Änderung an Methoden, die Exceptions werfen.
• Wenn eine Exception-Klasse verwendet wird, die höher in der Vererbungskette liegt, als die ursprüngliche. Zum Beispiel, wenn Sie in einer neueren Version eine PEAR_Exception werfen würden, in der alten aber z.B. PEAR_IOException verwendet haben.

Dinge, die nicht zum Bruch führen:

• Wenn eine abgeleitete Klasse der originalen Exception verwendet wird. Zum Beispiel, wenn Sie in der aktuellen Version eine PEAR_IOException werfen, und in älteren Versionen PEAR_Exception. Natürlich nur unter der Voraussetzung, dass PEAR_IOException von PEAR_Exception) abgeleitet ist.

16.  Best practices

Es gibt einige andere Dinge, die nicht vom PEAR Coding Standard betroffen sind, sondern von den persönlichen Gewohnheiten abhängen und nicht die Lesbarkeit unmittelbar berühren. Das betrifft z.B. die Frage 'Einfache oder doppelte Anführungszeichen'. Es handelt sich um Konstrukte, welche die Programmierung vereinfachen ohne konkrete Probleme zu verursachsen. Welche dieser 'üblichen' Praktiken genutzt wird, diese Entscheidung ist dem Programmierer überlassen. Wichtiger ist die konsequente Anwendung der eigenen Entscheidung in einem Package. Respektieren Sie die Entscheidung des verantwortlichen Programmierers, wenn Sie fremde Packages verändern.

17.  Beispieldatei inklusive Docblock-Kommentaren

Der Quellcode von PEAR-Packages wird von tausenden von Menschen gelesen. Genauso kann es passieren, dass andere einmal an Ihrem Package entwicklen werden. Um es ihnen leichter zu machen, ist die Formatierung des Quellcode und der Docblöcke standarisiert. Damit können Andere Informationen einfacher finden, das sie wissen, wo sie suchen müssen.

Jeder Docblock im Beispiel enthält viele Details wie Sie die Kommentare schreiben sollten. Diese Instruktionen sind aus zwei Gründen wichtig. Erstens können Benutzer und Entwickler schneller verstehen, was Ihr Code tut. Zweitens wird auf der PEAR-Webseite die Quellcode-Dokumentation für jedes Release von jedem Package bereitgestellt und Sie sollten auch dafür sorgen, dass diese Möglichkeit sinnvoll genutzt werden kann.

Bitte achten Sie auch auf den Einsatz von vertikalen und horizontalen Leerräumen. Sie sind Bestandteil der Standards.

Die „Fold Markers“ (// {{{ und // }}}) sind optional. Wenn Sie nicht benötigt werden, entfernen Sie die Einstellung foldmethod=marker aus dem Block mit Vim-Einstellungen.

(Quelle: PEAR Coding Standard, 05.02.2008)