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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 16734 -->
<!-- Reviewed: no -->
<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 im Zend Framework mitarbeiten. Viele Entwickler die
                den Zend Framework verwenden haben diese Code Standards als nützlich empfunden weil
                Ihr Code Stil mit jedem Zend Framework Code konsistent bleibt. Es ist auch
                anzumerken das es signifikant viel Arbeit erfordert einen kompletten Coding
                Standard zu definieren.

                Beachte: Manchmal entscheiden Entwickler das die Verfügbarkeit eines Standards
                wichtiger ist als was der Standard aktuell im höchsten Level des Designs empfiehlt.
                Diese Richtlinien im Zend Framework Coding Standard beschreiben die Praxis die im
                ZF Projekt sehr gut funktionieren. Diese Standard können geändert oder so wie sie
                sind verwendet werden solange Sie sich an unsere
                <ulink url="http://framework.zend.com/license">Lizenz</ulink> halten.
            </para>

            <para>
                Die Bereiche die im ZF Coding Standard abgedeckt werden enthalten:
            </para>

            <itemizedlist>
                <listitem>
                    <para><acronym>PHP</acronym> Dateiformatierung</para>
                </listitem>

                <listitem>
                    <para>Namens Konventionen</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 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.
            </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 das versehentlich Leerzeilen in die Antwort eingefügt
                werden.
            </para>

            <note>
                <para>
                    <emphasis>Wichtig</emphasis>: Einbeziehen von beliebigen binärischen Daten
                    durch <methodname>__HALT_COMPILER()</methodname> ist in den
                    <acronym>PHP</acronym> Dateien im Zend Framework oder abgeleiteten Datei
                    verboten. Das Benutzen ist nur für einige Installationsskirpte 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 Unix Textdatei Konvention. Zeilen müssen mit
                einem einzelnen Zeilenvorschubzeichen (LF) enden. Zeilenvorschub Zeicen werden duch
                eine ordinale 10, oder durch 0x0A (hexadecimal) dargestellt.
            </para>

            <para>
                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).
            </para>
        </sect2>
    </sect1>

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

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

            <para>
                Zend Framework standartisiert eine Klassennamen Konvention wobei die Namen der
                Klassen direkt mit den Verzeichnissen übereinstimmen muß in welchen Sie gespeichert
                sind. Das Basisverzeichnis der ZF Standard Bibliothek ist das "Zend/" Verzeichnis,
                wobei das Basisverzeichnis der ZF Extras Bibliothek im "ZendX/" Verzeichnis ist.
                Alle Zend Framework Klassen werden hierarchisch unter dem gleichen Basisverzeichnis
                gespeichert.
            </para>

            <para>
                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
                "<filename>Zend/Db/Table.php</filename>" muß übereinstimmen mit dem Klassennamen
                "<classname>Zend_Db_Table</classname>".
            </para>

            <para>
                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
                "<classname>Zend_Pdf</classname>" ist akzeptierbar.
            </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>
                Siehe die Klassennamen in der Standard und Extra Bibliothek für Beispiel dieser
                Klassennamen Konvention.
            </para>

            <note>
                <para>
                    <emphasis>Wichtig</emphasis>: 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.
                </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">Klasses</link>, 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 <classname>Zend_Controller_Plugin_Abstract</classname> als ungültig
                angenommen, aber <classname>Zend_Controller_PluginAbstract</classname> oder
                <classname>Zend_Controller_Plugin_PluginAbstract</classname> wären gültige Namen.
            </para>

            <note>
                <para>
                    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.
                </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">Klasses</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
                angenommen, aber <classname>Zend_Controller_PluginInterface</classname> oder
                <classname>Zend_Controller_Plugin_PluginInterface</classname> wären gültige Namen.
            </para>

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

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

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

            <para>
                Für alle anderen Dateien sind nur alphanummerische 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 Alphanummerische Zeichen enthalten. Unterstriche sind
                nicht gestattet. Nummern 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, muß der erste Buchstabe jeden Wortes
                großgeschrieben werden. Das wird normalerweise "camelCase" Formatierung genannt.
            </para>

            <para>
                Wortreichtum wird generell befürwortet. Funktionsnamen sollten so wortreich 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 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.
            </para>

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

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

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

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

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

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

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

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

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

            <para>
                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.
            </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 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.
            </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 muß 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 nie angegeben werden (Siehe
                <xref linkend="coding-standard.php-file-formatting.general"/>).
            </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 "doppeltes Anführungszeichen" abzugrenzen. Das ist
                    speziell für <acronym>SQL</acronym> 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 Ausbruch von Apostrophs, da Sie
                    viel einfacher lesbar ist.
                </para>
            </sect3>

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

                <para>
                    Variabler Austausch ist gestatten 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 muß 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>Nummerisch indizierte Arrays</title>

                <para>Negative Nummern sind in Indezes nicht gestattet.</para>

                <para>
                    Ein indiziertes Array kann mit mit irgendeiner nicht-negativen Nummer beginnen,
                    trotzdem sind alle BasisIndex neben 0 nicht erlaubt.
                </para>

                <para>
                    Wenn indizierte Arrays mit dem <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 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:
                </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 bei zusätzlichen Zeilen, und hilft
                    sicherzustellen das 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 muß
                    jede folgende Linie mit Leerraum aufgefüllt werden so das beide, 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 das 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 das 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 muß einen Dokumentationsblock haben der dem PHPDocumentor Standard
                    entspricht.
                </para>

                <para>
                    Jeder Code in der Klasse muß 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 seperieren.
                </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 die
                    Interfaces zu separieren, und die Namen des Interfaces so einzurücken das 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 muß am Beginn der Klasse
                    ausgelistet werden, vor der Deklaration von allen Methoden.
                </para>

                <para>
                    Das <code>var</code> Konstrukt ist nicht gestattet. Klassenvariablen definieren
                    Ihre Sichtbarkeit durch die Verwendung des <code>private</code>,
                    <code>protected</code>, oder <code>public</code> 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 <code>private</code>, <code>protected</code>, oder <code>public</code>
                    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:

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

                <note>
                    <para>
                        <emphasis>Notiz</emphasis>: Die Übergabe per Referenz ist die 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 Funktions Deklarationen 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 <code>if</code> und <code>elseif</code>
                    Konstrukten beruhen müssen ein einzelnes Leerzeichen vor der öffnenden Klammer
                    der bedingten Anweisung und ein einzelnes Leerzeichen nach der schließenden
                    Klammer.
                </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 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.
                </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 <code>default</code> Konstrukt darf nie bei der <code>switch</code>
                    Anweisung vergessen werden.
                </para>

                <note>
                    <para>
                        <emphasis>Notiz</emphasis>: Es ist machmal nützlich eine <code>case</code>
                        Anweisung zu schreiben, die durch das nächste case fällt indem innerhalb
                        solcher Fälle kein <code>break</code> oder <code>return</code> angegeben
                        wird. Um diese Fälle von Fehlern zu unterscheiden, sollte jede
                        <code>case</code> Anweisung in der <code>break</code> oder
                        <code>return</code> unterlassen werden einen Kommentar enthalten der
                        anzeigt das 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>Dokumentations Format</title>

                <para>
                    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:
                    <ulink url="http://phpdoc.org/">http://phpdoc.org"></ulink>
                </para>

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

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

                <para>
                    Jede Datei die <acronym>PHP</acronym> Code enthält muß 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
 *
 * @copyright  2008 Zend Technologies
 * @license    http://framework.zend.com/license   BSD License
 * @version    $Id:$
 * @link       http://framework.zend.com/package/PackageName
 * @since      Datei vorhanden seit Release 1.2.0
*/
]]></programlisting>
            </sect3>

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

                <para>
                    Jede Klasse muß einen Docblock haben welche 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)...
 *
 * @copyright  2008 Zend Technologies
 * @license    http://framework.zend.com/license   BSD License
 * @version    Release: @package_version@
 * @link       http://framework.zend.com/package/PackageName
 * @since      Klasse vorhanden seit Release 1.5.0
 * @deprecated Klasse abgeraten ab Release 2.0.0
 */
]]></programlisting>
            </sect3>

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

                <para>
                    Jede Funktion, auch Objekt Methoden, 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>
<!--
vim:se ts=4 sw=4 et:
-->