repo_zf1/documentation/manual/de/ref/coding_standard.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 21740 -->
<!-- Reviewed: 21740 -->
<appendix id="coding-standard">
    <title>Zend Framework Coding Standard für PHP</title>

    <sect1 id="coding-standard.overview">
        <title>Übersicht</title>

        <sect2 id="coding-standard.overview.scope">
            <title>Geltungsbereich</title>

            <para>
                Dieses Dokument bietet Richtlinien für die Formatierung von Code und Dokumentation
                für Individuen und Teams, die am Zend Framework mitarbeiten. Viele Entwickler, die
                das Zend Framework verwenden, halten diesen Coding Standard für nützlich, weil
                ihr Code Stil zum gesamten Zend Framework Code konsistent bleibt. Es ist auch
                anzumerken, dass es erhebliche Aufwand erfordert, einen kompletten Coding
                Standard zu definieren.
            </para>

            <note>
                <para>
                    Manchmal halten Entwickler die Schaffung eines Standards für wichtiger,
                    als das was der Standard eigentlich in der tiefsten Gliederungsebene des Designs empfiehlt.
                    Diese Richtlinien im Zend Framework Coding Standard beschreiben die Praxis, die im
                    Zend Framework Projekt sehr gut funktioniert. Dieser Standard kann geändert
                    oder so wie er ist verwendet werden, solange Sie sich an unsere
                    <ulink url="http://framework.zend.com/license">Lizenz</ulink> halten.
                </para>
            </note>

            <para>
                Die Bereiche, die im Zend Framework Coding Standard abgedeckt werden, enthalten:
            </para>

            <itemizedlist>
                <listitem><para><acronym>PHP</acronym>-Dateiformatierung</para></listitem>
                <listitem><para>Namenskonventionen</para></listitem>
                <listitem><para>Code Stil</para></listitem>
                <listitem><para>Inline-Dokumentation</para></listitem>
            </itemizedlist>
        </sect2>

        <sect2 id="coding-standard.overview.goals">
            <title>Ziele</title>

            <para>
                Coding Standards sind in jedem Entwicklungsprojekt wichtig, aber sie sind speziell
                dann wichtig, wenn viele Entwickler am gleichen Projekt arbeiten. Coding
                Standards helfen sicherzustellen, dass der Code von hoher Qualität ist, weniger
                Fehler hat und einfach zu warten ist.
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.php-file-formatting">
        <title>PHP-Dateiformatierung</title>

        <sect2 id="coding-standard.php-file-formatting.general">
            <title>Allgemein</title>

            <para>
                Für Dateien, welche nur <acronym>PHP</acronym>-Code beinhalten, ist der schliessende
                Tag ("?>") nicht zugelassen. Er wird von <acronym>PHP</acronym> nicht benötigt und
                das Weglassen verhindert, dass versehentlich Leerzeilen in die Antwort eingefügt
                werden.
            </para>

            <note>
                <para>
                    <emphasis>Wichtig</emphasis>: Einbeziehen von beliebigen binären Daten
                    durch <methodname>__HALT_COMPILER()</methodname> ist in den
                    <acronym>PHP</acronym>-Dateien im Zend Framework oder abgeleiteten Dateien
                    verboten. Das Benutzen ist nur für einige Installationsskripte erlaubt.
                </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.php-file-formatting.indentation">
            <title>Einrücken</title>

            <para>
                Ein Einzug sollte aus 4 Leerzeichen bestehen. Tabulatoren sind nicht erlaubt.
            </para>
        </sect2>

        <sect2 id="coding-standard.php-file-formatting.max-line-length">
            <title>Maximale Zeilenlänge</title>

            <para>
                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 <acronym>PHP</acronym>
                Codezeile beträgt 120 Zeichen.
            </para>
        </sect2>

        <sect2 id="coding-standard.php-file-formatting.line-termination">
            <title>Zeilenbegrenzung</title>

            <para>
                Die Zeilenbegrenzung folgt der Konvention für Unix-Textdateien. Zeilen müssen mit
                einem einzelnen Zeilenvorschubzeichen (LF) enden. Zeilenvorschubzeichen werden durch
                eine ordinale 10, oder durch 0x0A (hexadezimal) dargestellt.
            </para>

            <para>
                Beachte: Benutze nicht den Wagenrücklauf (CR) wie in den Konventionen von Apples
                OS (0x0D) oder die Kombination aus Wagenrücklauf und Zeilenvorschub
                (<acronym>CRLF</acronym>) wie im Standard für das Windows OS (0x0D, 0x0A).
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.naming-conventions">
        <title>Namenskonventionen</title>

        <sect2 id="coding-standard.naming-conventions.classes">
            <title>Klassen</title>

            <para>
                Zend Framework standardisiert eine Klassennamenkonvention, wobei die Namen der
                Klassen direkt mit den Verzeichnissen übereinstimmen müssen, 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.
            </para>

            <para>
                Klassennamen dürfen nur alphanumerische Zeichen enthalten. Ziffern sind in
                Klassennamen gestattet, es wird aber in den meisten Fällen davon abgeraten.
                Unterstriche sind nur statt des Pfadtrenners gestattet -- der Dateiname
                "<filename>Zend/Db/Table.php</filename>" muss übereinstimmen mit dem Klassennamen
                "<classname>Zend_Db_Table</classname>".
            </para>

            <para>
                Wenn ein Klassenname aus mehr als einem Wort besteht, muss 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
                "<classname>Zend_Pdf</classname>" ist akzeptabel.
            </para>

            <para>
                Diese Konventionen definieren einen Pseudo-Namespace Mechanismus für Zend
                Framework. Zend Framework wird das <acronym>PHP</acronym> Namespace Feature
                einbauen, sobald es verfügbar ist und es für unsere Entwickler in deren Anwendungen
                ohne Bedenken verwendbar ist.
            </para>

            <para>
                Als Beispiel dieser Klassennamenkonvention sei auf die Klassennamen
                in der Standard und der Extra Bibliothek verwiesen.
            </para>

            <note>
                <para>
                    <emphasis>Wichtig</emphasis>: Klassenname in Code, welcher mit dem Framework ausgeliefert
                    werden muss, 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.
                </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.abstracts">
            <title>Abstrakte Klassen</title>

            <para>
                Generell folgen abstrakte Klassen der gleichen Konvention wie <link
                    linkend="coding-standard.naming-conventions.classes">Klassen</link>, mit einer
                zusätzlichen Regel: Die Namen von abstrakten Klassen müssen mit dem Term
                "Abstract" enden, und dem Term darf kein Unterstrich vorangestellt sein. Als
                Beispiel wird <classname>Zend_Controller_Plugin_Abstract</classname> als ungültig
                betrachtet, aber <classname>Zend_Controller_PluginAbstract</classname> oder
                <classname>Zend_Controller_Plugin_PluginAbstract</classname> wären gültige Namen.
            </para>

            <note>
                <para>
                    Diese Namenskonvention ist neu seit Version 1.9.0 des Zend Frameworks. Bei
                    Klassen vor dieser Version kann es sein, dass sie dieser Regel nicht folgen, aber
                    sie werden in Zukunft umbenannt, um ihr zu entsprechen.
                </para>

                <para>
                    Der Hintergrund dieser Änderung ist die Verwendung von Namespaces. Da wir auf
                    Zend Framework 2.0 und die Verwendung von <acronym>PHP</acronym> 5.3 zugehen,
                    werden wir Namespaces verwenden. Der einfachste Weg, die Konvertierung zu
                    Namespaces zu automatisieren, besteht darin, die Unterstriche in Namespace
                    Separatoren zu konvertieren -- aber in der alten Namenskonvention, lässt dies
                    den Klassennamen einfach als "Abstract" oder "Interface" zurück" -- beide sind
                    reservierte Schlüsselwörter in <acronym>PHP</acronym>. Wenn wir den Namen der
                    (Unter)Komponente dem Klassennamen voranstellen, können wir diese Probleme
                    vermeiden.
                </para>

                <para>
                    Um die Situation zu illustrieren, nehmen wir an, dass die Klasse
                    <classname>Zend_Controller_Request_Abstract</classname> konvertiert wird, um
                    Namespaces zu verwenden:
                </para>

                <programlisting language="php"><![CDATA[
namespace Zend\Controller\Request;

abstract class Abstract
{
    // ...
}
]]></programlisting>

                <para>
                    Natürlich wird das nicht funktionieren. In der neuen Namenskonvention würde
                    dies aber trotzdem zu folgendem werden:
                </para>
                <programlisting language="php"><![CDATA[
namespace Zend\Controller\Request;

abstract class RequestAbstract
{
    // ...
}
]]></programlisting>

                <para>
                    Wir bleiben trotzdem bei der Semantik und der Trennung auf Namespaces, während
                    wir die Probleme mit den Schlüsselworten vermeiden; gleichzeitig beschreibt dies
                    abstrakte Klassen besser.
                </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.interfaces">
            <title>Interfaces</title>

            <para>
                Generell folgen Interfaces der gleichen Konvention wie <link
                    linkend="coding-standard.naming-conventions.classes">Klassen</link>, 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 <classname>Zend_Controller_Plugin_Interface</classname> als ungültig
                betrachtet, aber <classname>Zend_Controller_PluginInterface</classname> oder
                <classname>Zend_Controller_Plugin_PluginInterface</classname> wären gültige Namen.
            </para>

            <para>
                Während diese Regel nicht benötigt wird, wird sie sehr empfohlen, da sie
                Entwicklern einen guten visuellen Hinweis gibt, welche Dateien ein Interface
                enthalten und welche Klassen.
            </para>

            <note>
                <para>
                    Diese Namenskonvention ist neu seit Version 1.9.0 des Zend Frameworks. Bei
                    Klassen vor dieser Version kann es sein, dass sie dieser Regel nicht folgen, aber
                    sie werden in Zukunft umbenannt um ihr zu entsprechen. Siehe <link
                        linkend="coding-standard.naming-conventions.abstracts">den vorhergehenden
                        Abschnitt</link> für weitere Informationen über die Hintergründe für diese
                    Änderung.
                </para>
            </note>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.filenames">
            <title>Dateinamen</title>

            <para>
                Für alle anderen Dateien sind nur alphanumerische Zeichen, Unterstriche und der
                Bindestrich ("-") gestattet. Leerzeichen sind völlig verboten.
            </para>

            <para>
                Jede Datei, die irgendeinen <acronym>PHP</acronym>-Code enthält, sollte mit der
                Endung "<filename>.php</filename>" enden, mit Ausnahme der View-Skripte. Die
                folgenden Beispiele zeigen akzeptierbare Dateinamen für Zend Framework Klassen:
            </para>

            <programlisting language="php"><![CDATA[
Zend/Db.php

Zend/Controller/Front.php

Zend/View/Helper/FormRadio.php
]]></programlisting>

            <para>
                Dateinamen müssen den Klassennamen wie oben beschrieben entsprechen.
            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.functions-and-methods">
            <title>Funktionen und Methoden</title>

            <para>
                Funktionsnamen dürfen nur alphanumerische Zeichen enthalten. Unterstriche sind
                nicht gestattet. Ziffern sind in Funktionsnamen gestattet, aber in den meisten
                Fällen nicht empfohlen.
            </para>

            <para>
                Funktionsnamen müssen immer mit einem Kleinbuchstaben anfangen. Wenn Funktionsnamen
                aus mehr als einem Wort bestehen, muss der erste Buchstabe jedes Worts
                großgeschrieben werden. Das wird häufig "camelCase"-Formatierung genannt.
            </para>

            <para>
                Ausführlichkeit wird generell befürwortet. Funktionsnamen sollten so ausführlich wie
                möglich sein, um deren Zweck und Verhalten zu erklären.
            </para>

            <para>
                Das sind Beispiele akzeptierbarer Namen für Funktionen:
            </para>

            <programlisting language="php"><![CDATA[
filterInput()

getElementById()

widgetFactory()
]]></programlisting>

            <para>
                Für objektorientiertes 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.
            </para>

            <para>
                 Für Methoden in Objekten, die mit dem Modifikator "private" oder "protected"
                 deklariert sind, muss 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
                 einen Unterstrich enthalten.
            </para>

            <para>
                Funktionen im globalen Bereich (auch "floating functions" genannt) sind gestattet,
                aber es wird in den meisten Fällen davon abgeraten. Diese Funktionen sollten
                in einer statischen Klasse gewrappt werden.
            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.variables">
            <title>Variablen</title>

            <para>
                Variablennamen dürfen nur alphanumerische Zeichen enthalten. Unterstriche sind
                nicht gestattet. Ziffern sind in Variablen gestattet in den meisten Fällen aber
                nicht empfohlen.
            </para>

            <para>
                Für Instanzvariablen, die mit dem Modifikator "private" oder "protected" deklariert
                werden, muss das erste Zeichen des Funktionsnamens ein einzelner Unterstrich sein.
                Das ist die einzige akzeptierte Anwendung eines Unterstriches in einem Variablennamen.
                Klassenvariablen, welche als "public" deklariert werden, sollten nie mit einem
                Unterstrich beginnen.
            </para>

            <para>
                Wie bei Funktionsnamen (siehe Abschnitt 3.3) müssen Variablennamen immer mit einem
                Kleinbuchstaben starten und der "camelCaps"-Schreibweise folgen.
            </para>

            <para>
                Ausführlichkeit wird generell befürwortet. Variablen sollen immer so ausführlich wie
                möglich sein, um die Daten zu beschreiben, die der Entwickler in ihnen zu speichern
                gedenkt. Von knappen Variablennamen wie "<varname>$i</varname>" und
                "<varname>$n</varname>" wird abgeraten für alles außer für kleinste Schleifen.
                Wenn eine Schleife mehr als 20 Codezeilen enthält sollten die Index-Variablen einen
                ausführlicheren Namen haben.
            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.constants">
            <title>Konstanten</title>

            <para>
                Konstanten können beides enthalten, sowohl alphanumerische Zeichen als auch
                Unterstriche. Ziffern sind in Konstantennamen gestattet.
            </para>

            <para>
                Alle Buchstaben, die in Konstantenname verwendet werden, müssen großgeschrieben werden,
                während Wörter in einem Konstantennamen durch Unterstriche getrennt werden müssen.
            </para>

            <para>
                Zum Beispiel ist <constant>EMBED_SUPPRESS_EMBED_EXCEPTION</constant> gestattet, aber
                <constant>EMBED_SUPPRESSEMBEDEXCEPTION</constant> nicht.
            </para>

            <para>
                Konstanten müssen als Klassenkonstanten mit dem Modifikator "const" definiert
                werden. Die Definition von Konstanten im globalen Bereich mit der "define"
                Funktion ist gestattet, aber es wird es wird stärkstens davon abgeraten.
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.coding-style">
        <title>Code Stil</title>

        <sect2 id="coding-standard.coding-style.php-code-demarcation">
            <title>PHP Code Abgrenzung</title>

            <para>
                <acronym>PHP</acronym> Code muss immer mit der kompletten Form des
                Standard-<acronym>PHP</acronym>-Tags abgegrenzt sein:
            </para>

            <programlisting language="php"><![CDATA[
<?php

?>
]]></programlisting>

            <para>
                Kurze Tags sind nie erlaubt. Für Dateien, die nur <acronym>PHP</acronym>-Code
                enthalten, darf das schließende Tag nicht angegeben werden (Siehe <link
                    linkend="coding-standard.php-file-formatting.general">generelle
                    Standards</link>).
            </para>
        </sect2>

        <sect2 id="coding-standard.coding-style.strings">
            <title>Strings</title>

            <sect3 id="coding-standard.coding-style.strings.literals">
                <title>String Literale</title>

                <para>
                    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:
                </para>

                <programlisting language="php"><![CDATA[
$a = 'Beispiel String';
]]></programlisting>
            </sect3>

            <sect3 id="coding-standard.coding-style.strings.literals-containing-apostrophes">
                <title>String Literale die Apostrophe enthalten</title>

                <para>
                    Wenn ein literaler String selbst Apostrophe enthält, ist es gestattet den String
                    mit Anführungszeichen oder "doppelten Anführungszeichen" abzugrenzen. Das ist
                    speziell für <constant>SQL</constant> Anweisungen nützlich:
                </para>

                <programlisting language="php"><![CDATA[
$sql = "SELECT `id`, `name` from `people` "
     . "WHERE `name`='Fred' OR `name`='Susan'";
]]></programlisting>

                <para>
                    Diese Syntax ist zu bevorzugen, im Gegensatz zum Entwerten des Apostrophs, da sie
                    viel einfacher lesbar ist.
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.strings.variable-substitution">
                <title>Variablensubstitution</title>

                <para>
                    Variablensubstitution ist gestattet bei Verwendung einer der Formen:
                </para>

                <programlisting language="php"><![CDATA[
$greeting = "Halle $name, willkommen zurück!";

$greeting = "Hallo {$name}, willkommen zurück!";
]]></programlisting>

                <para>
                    Aus Gründen der Konstistenz ist folgende Form nicht gestattet:
                </para>

                <programlisting language="php"><![CDATA[
$greeting = "Hallo ${name}, willkommen zurück!";
]]></programlisting>
            </sect3>

            <sect3 id="coding-standard.coding-style.strings.string-concatenation">
                <title>Verbinden von Strings</title>

                <para>
                    Strings müssen verbunden werden, indem man den "." Operator verwendet. Ein
                    Leerzeichen muss immer vor und nach dem "." Operator hinzugefügt werden, um die
                    Lesbarkeit zu erhöhen:
                </para>

                <programlisting language="php"><![CDATA[
$company = 'Zend' . ' ' . 'Technologies';
]]></programlisting>

                <para>
                    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:
                </para>

                <programlisting language="php"><![CDATA[
$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";
]]></programlisting>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.arrays">
            <title>Arrays</title>

            <sect3 id="coding-standard.coding-style.arrays.numerically-indexed">
                <title>Numerisch indizierte Arrays</title>

                <para>Negative Zahlen sind in Indizes nicht gestattet.</para>

                <para>
                    Ein indiziertes Array kann mit irgendeiner nicht-negativen Zahl beginnen,
                    trotzdem sind alle BasisIndices außer 0 nicht erlaubt.
                </para>

                <para>
                    Wenn indizierte Arrays mit der <type>Array</type>-Funktion deklariert werden,
                    muß ein folgendes Leerzeichen nach jeder Kommabegrenzung hinzugefügt werden, um
                    die Lesbarkeit zu erhöhen:
                </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array(1, 2, 3, 'Zend', 'Studio');
]]></programlisting>

                <para>
                    Es ist bei Verwendung des "array" Konstrukts gestattet, mehrzeilige indizierte
                    Arrays zu definieren. In diesem Fall, muss jede folgende Zeile mit Leerzeichen
                    aufgefüllt werden, so dass der Beginn jeder Zeile ausgerichtet ist:
                </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500);
]]></programlisting>

                <para>
                    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:
                </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array(
    1, 2, 3, 'Zend', 'Studio',
    $a, $b, $c,
    56.44, $d, 500,
);
]]></programlisting>

                <para>
                    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 mit zusätzlichen Zeilen und hilft
                    sicherzustellen, dass durch ein fehlendes Komma keine Parsing-Fehler auftreten.
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.arrays.associative">
                <title>Assoziative Arrays</title>

                <para>
                    Wenn assoziative Arrays mit dem <type>Array</type>-Konstrukt deklariert werden,
                    ist das Umbrechen der Anweisung in mehrere Zeilen gestattet. In diesem Fall muss
                    jede folgende Zeile mit Leerraum aufgefüllt werden, so dass sowohl der Schlüssel
                    und der Wert untereinander stehen:
                </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');
]]></programlisting>

                <para>
                    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, dass sie untereinander stehen.
                </para>

                <programlisting language="php"><![CDATA[
$sampleArray = array(
    'firstKey'  => 'firstValue',
    'secondKey' => 'secondValue',
);
]]></programlisting>

                <para>
                    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, dass durch ein fehlendes Komma keine Parsing-Fehler auftreten.
                </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.classes">
            <title>Klassen</title>

            <sect3 id="coding-standard.coding-style.classes.declaration">
                <title>Klassen-Deklarationen</title>

                <para>
                    Klassen müssen entsprechend der Zend Framework Namenskonvention benannt werden.
                </para>

                <para>
                    Die Klammer sollte immer in der Zeile unter dem Klassennamen geschrieben werden.
                </para>

                <para>
                    Jede Klasse muss einen Dokumentationsblock haben der dem PHPDocumentor-Standard
                    entspricht.
                </para>

                <para>
                    Jeder Code in der Klasse muss mit vier Leerzeichen eingerückt sein.
                </para>

                <para>
                    Nur eine Klasse ist in jeder <acronym>PHP</acronym>-Datei gestattet.
                </para>

                <para>
                    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 <acronym>PHP</acronym>-Code in der Datei trennen.
                </para>

                <para>
                    Das folgende ist ein Beispiel einer akzeptierbaren Klassendeklaration:
                </para>

                <programlisting language="php"><![CDATA[
/**
 * Dokumentations Block hier
 */
class SampleClass
{
    // gesamter Inhalt der Klasse
    // muss mit vier Leerzeichen eingerückt sein
}
]]></programlisting>

                <para>
                    Klassen, die andere Klassen erweitern oder welche Interfaces implementieren,
                    sollen ihre Abhängigkeit auf der gleichen Zeile deklarieren, wenn das möglich
                    ist.
                </para>

                <programlisting language="php"><![CDATA[
class SampleClass extends FooAbstract implements BarInterface
{
}
]]></programlisting>

                <para>
                    Wenn als Ergebnis so einer Deklaration, die Länge der Zeile die <link
                        linkend="coding-standard.php-file-formatting.max-line-length">Maximale
                        Zeilenlänge</link> überschreitet, ist die Zeile vor dem "extends" und
                    oder "implements" Schlüsselwort umzubrechen und diese Zeilen um ein
                    Einrückungslevel einzurücken.
                </para>

                <programlisting language="php"><![CDATA[
class SampleClass
    extends FooAbstract
    implements BarInterface
{
}
]]></programlisting>

                <para>
                    Wenn die Klasse mehrere Interfaces implementiert und die Deklaration die
                    maximale Zeilenlänge übersteigt, ist nach jedem Komma umzubrechen und sind die
                    Interfaces zu separieren und die Namen der Interfaces so einzurücken, dass sie
                    untereinander stehen.
                </para>

                <programlisting language="php"><![CDATA[
class SampleClass
    implements BarInterface,
               BazInterface
{
}
]]></programlisting>
            </sect3>

            <sect3 id="coding-standard.coding-style.classes.member-variables">
                <title>Klassenvariablen</title>

                <para>
                    Klassenvariablen müssen entsprechend den Variablen-Benennungs-Konventionen des
                    Zend Frameworks benannt werden.
                </para>

                <para>
                    Jede Variable, die in der Klasse deklariert wird, muss am Beginn der Klasse
                    vor der Deklaration von allen Methoden aufgelistet werden.
                </para>

                <para>
                    Das <emphasis>var</emphasis> Konstrukt ist nicht gestattet. Klassenvariablen
                    definieren Ihre Sichtbarkeit durch die Verwendung des
                    <property>private</property>, <property>protected</property> oder
                    <property>public</property> 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
                    &amp; get).
                </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.functions-and-methods">
            <title>Funktionen und Methoden</title>

            <sect3 id="coding-standard.coding-style.functions-and-methods.declaration">
                <title>Deklaration von Funktionen und Methoden</title>

                <para>
                    Funktionen müssen nach der Funktions-Namenskonvention des Zend Frameworks
                    benannt werden.
                </para>

                <para>
                    Methoden innerhalb von Klassen müssen immer ihre Sichtbarkeit durch Verwendung
                    einer der <property>private</property>, <property>protected</property>, oder
                    <property>public</property> Modifikatoren definieren.
                </para>

                <para>
                    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.
                </para>

                <para>
                    Von Funktionen im globalen Raum wird komplett abgeraten.
                </para>

                <para>
                    Das folgende ist ein Beispiel einer akzeptierbaren Funktionsdeklaration in einer
                    Klasse:
                </para>

                <programlisting language="php"><![CDATA[
/**
 * Dokumentations Block hier
 */
class Foo
{
    /**
     * Dokumentations Block hier
     */
    public function bar()
    {
        // gesamter Inhalt der Funktion
        // muss durch view Leerzeichen eingerückt sein
    }
}
]]></programlisting>

                <para>
                    In den Fällen wo die Liste der Argumente die <link
                        linkend="coding-standard.php-file-formatting.max-line-length">maximale
                        Zeilenlänge</link> ü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:
                </para>

                <programlisting language="php"><![CDATA[
/**
 * Dokumentations Block Hier
 */
class Foo
{
    /**
     * Dokumentations Block Hier
     */
    public function bar($arg1, $arg2, $arg3,
        $arg4, $arg5, $arg6
    ) {
        // gesamter Inhalt der Funktion
        // muss durch view Leerzeichen eingerückt sein
    }
}
]]></programlisting>

                <note>
                    <para>
                        <emphasis>Notiz</emphasis>: Die Übergabe per Referenz ist der einzige
                        erlaubt Mechanismus für die Übergabe von Parametern in der Deklaration
                        einer Funktion:
                    </para>
                </note>

                <programlisting language="php"><![CDATA[
/**
 * Dokumentations Block hier
 */
class Foo
{
    /**
     * Dokumentations Block hier
     */
    public function bar(&$baz)
    {}
}
]]></programlisting>

                <para>
                    Der Aufruf durch Referenz ist nicht gestattet.
                </para>

                <para>
                    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.
                </para>

                <programlisting language="php"><![CDATA[
/**
 * Dokumentations Block hier
 */
class Foo
{
    /**
     * FALSCH
     */
    public function bar()
    {
        return($this->bar);
    }

    /**
     * RICHTIG
     */
    public function bar()
    {
        return $this->bar;
    }
}
]]></programlisting>
            </sect3>

            <sect3 id="coding-standard.coding-style.functions-and-methods.usage">
                <title>Verwendung von Funktionen und Methoden</title>

                <para>
                    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:
                </para>

                <programlisting language="php"><![CDATA[
threeArguments(1, 2, 3);
]]></programlisting>

                <para>
                    Übergabe von Referenzen zur Laufzeit ist strengstens verboten. Siehe die Sektion
                    für Funktionsdeklarationen für den richtigen Weg um Funktionsargumente per
                    Referenz zu übergeben.
                </para>

                <para>
                    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:
                </para>

                <programlisting language="php"><![CDATA[
threeArguments(array(1, 2, 3), 2, 3);

threeArguments(array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500), 2, 3);

threeArguments(array(
    1, 2, 3, 'Zend', 'Studio',
    $a, $b, $c,
    56.44, $d, 500
), 2, 3);
]]></programlisting>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.control-statements">
            <title>Kontrollanweisungen</title>

            <sect3 id="coding-standard.coding-style.control-statements.if-else-elseif">
                <title>If/Else/Elseif</title>

                <para>
                    Kontrollanweisungen, die auf den <emphasis>if</emphasis> und
                    <emphasis>elseif</emphasis> Konstrukten beruhen müssen ein einzelnes
                    Leerzeichen vor der öffnenden Klammer der bedingten Anweisung und ein
                    einzelnes Leerzeichen nach der schließenden Klammer haben.
                </para>

                <para>
                    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.
                </para>

                <para>
                    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.
                </para>

                <programlisting language="php"><![CDATA[
if ($a != 2) {
    $a = 2;
}
]]></programlisting>

                <para>
                    Wenn die Kontrollanweisung die Ursache für eine Überschreitung der <link
                        linkend="coding-standard.php-file-formatting.max-line-length">maximalen
                        Zeilenlänge</link> 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.
                </para>

                <programlisting language="php"><![CDATA[
if (($a == $b)
    && ($b == $c)
    || (Foo::CONST == $d)
) {
    $a = $d;
}
]]></programlisting>

                <para>
                    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.
                </para>

                <para>
                    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:
                </para>

                <programlisting language="php"><![CDATA[
if ($a != 2) {
    $a = 2;
} else {
    $a = 7;
}

if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
    $a = 4;
} else {
    $a = 7;
}

if (($a == $b)
    && ($b == $c)
    || (Foo::CONST == $d)
) {
    $a = $d;
} elseif (($a != $b)
          || ($b != $c)
) {
    $a = $c;
} else {
    $a = $b;
}
]]></programlisting>

                <para>
                    <acronym>PHP</acronym> erlaubt in einigen Fällen auch Anweisungen ohne
                    Klammern. Dieser Coding Standard macht keine Unterscheidungen und
                    es müssen alle "if", "elseif" oder "else" Anweisungen in Klammern geschrieben
                    werden.
                </para>
            </sect3>

            <sect3 id="coding-standards.coding-style.control-statements.switch">
                <title>Switch</title>

                <para>
                    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.
                </para>

                <para>
                    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.
                </para>

                <programlisting language="php"><![CDATA[
switch ($numPeople) {
    case 1:
        break;

    case 2:
        break;

    default:
        break;
}
]]></programlisting>

                <para>
                    Das <property>default</property> Konstrukt darf nie bei der
                    <property>switch</property> Anweisung vergessen werden.
                </para>

                <note>
                    <para>
                        <emphasis>Notiz</emphasis>: Es ist machmal nützlich eine
                        <property>case</property>-Anweisung zu schreiben, die durch das nächste case
                        fällt, indem innerhalb solcher Fälle kein <property>break</property> oder
                        <property>return</property> angegeben wird. Um diese Fälle von Fehlern zu
                        unterscheiden, sollte jede <property>case</property>-Anweisung, in der
                        <property>break</property> oder <property>return</property> unterlassen
                        werden, einen Kommentar enthalten, der anzeigt, dass das break gewünschtermaßen
                        unterdrückt wurde.
                    </para>
                </note>
            </sect3>
        </sect2>

        <sect2 id="coding-standards.inline-documentation">
            <title>Inline Dokumentation</title>

            <sect3 id="coding-standards.inline-documentation.documentation-format">
                <title>Dokumentationsformat</title>

                <para>
                    Alle Dokumentationsblöcke ("DocBlock") müssen mit dem phpDocumentor-Format
                    kompatibel sein. Die Beschreibung des phpDocumentor-Formats ist nicht
                    Thema dieses Dokuments. Für weiterführende Informationen siehe:
                    <ulink url="http://phpdoc.org/">http://phpdoc.org"></ulink>
                </para>

                <para>
                    Alle Klassendateien müssen einen "file-level" Docblock am Beginn jeder Datei
                    und einen "class-level" Docblock direkt oberhalb jeder Klasse enthalten.
                    Beispiele solcher Docblocks können im folgenden gefunden werden.
                </para>
            </sect3>

            <sect3 id="coding-standards.inline-documentation.files">
                <title>Dateien</title>

                <para>
                    Jede Datei, die <acronym>PHP</acronym> Code enthält, muss einen Docblock am Beginn
                    der Datei besitzen, welcher mindestens diese phpDocumentor-Tags enthält:
                </para>

                <programlisting language="php"><![CDATA[
/**
 * Kurze Beschreibung der Datei
 *
 * Lange Beschreibung der Datei (wenn vorhanden)...
 *
 * LICENSE: Einige Lizenz Informationen
 *
 * @category   Zend
 * @package    Zend_Magic
 * @subpackage Wand
 * @copyright  Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
 * @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
*/
]]></programlisting>

                <para>
                    Das <property>@category</property> Tag muß den Wert "Zend" haben.
                </para>

                <para>
                    Das <property>@package</property> 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, das Präfix "Zend", und
                    den Namen der Komponente.
                </para>

                <para>
                    Das <property>@subpackage</property> Tag ist optional. Wenn es angegeben wird,
                    sollte es der Name der Subkomponente sein, ohne das Präfix der Klasse. Im
                    obigen Beispiel ist die Annahme, dass die Klasse in der Datei entweder
                    "<classname>Zend_Magic_Wand</classname>" ist oder den Klassennamen als Teil
                    seines Präfixes verwendet.
                </para>
            </sect3>

            <sect3 id="coding-standards.inline-documentation.classes">
                <title>Klassen</title>

                <para>
                    Jede Klasse muss einen Docblock haben, welcher mindestens diese phpDocumentor Tags
                    enthält:
                </para>

                <programlisting language="php"><![CDATA[
/**
 * Kurze Beschreibung für die Klasse
 *
 * Lange Beschreibung für die Klasse (wenn vorhanden)...
 *
 * @category   Zend
 * @package    Zend_Magic
 * @subpackage Wand
 * @copyright  Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
 * @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
 */
]]></programlisting>

                <para>
                    Das <property>@category</property> Tag muß den Wert "Zend" haben.
                </para>

                <para>
                    Das <property>@package</property> 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.
                </para>

                <para>
                    Das <property>@subpackage</property> Tag ist optional. Wenn es angegeben wird,
                    sollte es der Name der Subkomponente sein, ohne das Präfix der Klasse. Im
                    obigen Beispiel ist die Annahme, dass die Klasse in der Datei entweder
                    "<classname>Zend_Magic_Wand</classname>" ist oder den Klassennamen als Teil
                    seines Präfixes verwendet.
                </para>
            </sect3>

            <sect3 id="coding-standards.inline-documentation.functions">
                <title>Funktionen</title>

                <para>
                    Jede Funktion, auch Objektmethoden, müssen einen Docblock haben, welcher
                    mindestens folgendes enthält:
                </para>

                <itemizedlist>
                    <listitem><para>Eine Beschreibung der Funktion</para></listitem>
                    <listitem><para>Alle Argumente</para></listitem>
                    <listitem><para>Alle möglichen Rückgabewerte</para></listitem>
                </itemizedlist>

                <para>
                    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.
                </para>

                <para>
                    Wenn eine Funktion oder Methode eine Ausnahme werfen könnte, muß @throws für
                    alle bekannten Exception Klassen verwendet werden:
                </para>

                <programlisting language="php"><![CDATA[
@throws exceptionclass [Beschreibung]
]]></programlisting>
            </sect3>
        </sect2>
    </sect1>
</appendix>