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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 14978 -->
<!-- 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:

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

                    <listitem>
                        <para>Namens Konventionen</para>
                    </listitem>

                    <listitem>
                        <para>Code Stil</para>
                    </listitem>

                    <listitem>
                        <para>Inline Dokumentation</para>
                    </listitem>
                </itemizedlist>
            </para>
        </sect2>

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

            <para>
                Coding Standards sind in jedem Entwicklungs Projekt wichtig, aber sie sid speziell
                dann wichtig wenn viele Entwickler an dem gleichen Projekt arbeiten. Coding
                Standards helfen sicherzustellen das der Code von hoher Qualität ist, weniger
                Fehler hat, und einfach zu warten ist.
            </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 PHP Code beinhalten ist der schliessende Tag ("?>") nicht
                zugelassen. Er wird von PHP nicht benötigt, und das Weglassen verhindert das
                versehentlich Leerzeilen in die Antwort eingefügt werden.
            </para>

            <para>
                <emphasis>WICHTIG:</emphasis> Einbeziehen von beliebigen binärischen Daten durch
                <code>__HALT_COMPILER()</code> ist in den PHP Dateien im Zend Framework oder
                abgeleiteten Datei verboten. Das Benutzen ist nur für einige Installationsskirpte
                erlaubt.
            </para>
        </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 Zeile 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
                "Zend/Db/Table.php" muß übereinstimmen mit dem Klassennamen "Zend_Db_Table".
            </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 "Zend_Pdf" ist
                akzeptierbar.
            </para>

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

            <para>
                Siehe die Klassennamen in der Standard und Extra Bibliothek für Beispiel dieser
                Klassennamen Konvention.

                <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>
        </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 PHP Code enthält sollte mit der Endung ".php" enden, mit
                Ausnahme der View Skripte. Die folgenden Beispiele zeigen akzeptierbare Dateinamen
                für Zend Framework Klassen:

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

Zend/Controller/Front.php

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

                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:

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

getElementById()

widgetFactory()
]]>
                </programlisting>
            </para>

            <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 <code>EMBED_SUPPRESS_EMBED_EXCEPTION</code> gestattet aber
                <code>EMBED_SUPPRESSEMBEDEXCEPTION</code> 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>
                PHP Code muß immer mit der kompletten Form des Standard-PHP Tags abgegrenzt sein:

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

?>
]]>
                </programlisting>
            </para>

            <para>
                Kurze Tags sind nie erlaubt. Für Dateien die nur PHP 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:

                    <programlisting role="php"><![CDATA[
$a = 'Beispiel String';
]]>
                    </programlisting>
                </para>
            </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
                    SQL Anweisungen nützlich:

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

                    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:

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

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

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

                    <programlisting role="php"><![CDATA[
$greeting = "Hallo ${name}, willkommen zurück!";
]]>
                    </programlisting>
                </para>
            </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:

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

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

                    <programlisting role="php"><![CDATA[
$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";
]]>
                    </programlisting>
                </para>
            </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 <code>array</code> Funktion deklariert werden, muß ein
                    folgendes Leerzeichen nach jeder Kommabegrenzung hinzugefügt werden um die Lesbarkeit
                    zu erhöhen:

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

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

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

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

                <para>
                    Wenn assoziative Arrays mit dem <code>array</code> 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:

                    <programlisting role="php"><![CDATA[
$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');
]]>
                    </programlisting>
                 </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 PHP 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 PHP
                    Code in der Datei seperieren.
                </para><para>
                    Das folgende ist ein Beispiel einer akzeptierbaren Klassendeklaration:

                    <programlisting role="php"><![CDATA[
/**
 * Dokumentations Block hier
 */
class SampleClass
{
    // gesamter Inhalt der Klasse
    // muss mit vier Leerzeichen eingerückt sein
}
]]>
                    </programlisting>
                </para>
            </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/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:

                    <programlisting role="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>

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

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

                <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 später auf Rückgabe durch
                    Referenz geändert wird.

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

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

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

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

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

                    <programlisting role="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);
]]>
                    </programlisting>
                </para>
            </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.

                    <programlisting role="php"><![CDATA[
if ($a != 2) {
    $a = 2;
}
]]>
                    </programlisting>
                </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:

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

if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
    $a = 4;
} else {
    $a = 7;
}
]]>
                    </programlisting>
                    PHP erlaubt das Anweisungen in einigen Fällen auch ohne Klammern zu schreiben.
                    Dieser Coding Standard macht keine Unterscheidungen und es müssen alle "if", "elseif" oder "else"
                    Anweisungen in Klammern geschrieben werden.
                </para>

                <para>
                    Die Verwendung des "elseif" Konstruktes ist erlaubt es wird aber strengstens davon abgeraten
                    und es ist die "else if" Kombination zu bevorzugen.
                </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 role="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>

                <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>
            </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 PHP Code enthält muß einen Docblock am Beginn der Datei besitzen welcher
                    mindestens diese phpDocumentor Tags enthält:

                    <programlisting role="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>
                </para>
            </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:

                    <programlisting role="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>
                </para>
            </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:

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

                <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/Methode eine Ausnahme werfen könnte, muß @throws für alle bekannten
                    Exception Klassen verwendet werden:

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

</appendix>
<!--
vim:se ts=4 sw=4 et:
-->