repo_zf1Php7/documentation/manual/fr/ref/coding_standard.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15343 -->
<!-- Reviewed: no -->
<appendix id="coding-standard">
    <title>Convention de codage PHP de Zend Framework</title>

    <sect1 id="coding-standard.overview">
        <title>Vue d'ensemble</title>

        <sect2 id="coding-standard.overview.scope">
            <title>Portée</title>

            <para>
                Ce document fournit les lignes directrices pour le formatage de code et la
                documentation pour les contributeurs individuels et les équipes contributrices à
                Zend Framework. Un certain nombre de développeurs utilisant Zend Framework ont
                trouvé ces conventions de codage pratique car leurs styles de codage sont cohérents
                avec l'ensemble du code de Zend Framework. Il est également à noter qu'il exige un
                effort significatif pour spécifier entièrement des normes de codage. Note: parfois
                les développeurs considèrent l'établissement d'une norme plus important que ce que
                cette norme suggère réellement en tout cas au niveau de l'analyse détaillée de la
                conception. Les lignes directrices dans les conventions de codage de Zend Framework
                effectuent un cliché des pratiques qui ont bien fonctionnées dans le projet Zend
                Framework. Vous pouvez modifier ces règles ou les utiliser comme telles en accord
                avec les termes de votre <ulink
                url="http://framework.zend.com/license">licence.</ulink>
            </para>

            <para>
                Les sujets traités dans les conventions de codage de Zend Framework sont :
                <itemizedlist>
                    <listitem>
                        <para>Formatage des fichiers PHP</para>
                    </listitem>

                    <listitem>
                        <para>Conventions de nommage</para>
                    </listitem>

                    <listitem>
                        <para>Style de code</para>
                    </listitem>

                    <listitem>
                        <para>Documentation en ligne</para>
                    </listitem>
                </itemizedlist>
            </para>
        </sect2>

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

            <para>
                De bonnes conventions de codage sont importantes dans tout projet de
                développement, et plus particulièrement lorsque plusieurs développeurs travaillent
                en même temps sur le projet. Avoir ces conventions permet de s'assurer que le code
                est de haute qualité, peu buggé et facilement maintenu.
            </para>
        </sect2>
    </sect1>

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

        <sect2 id="coding-standard.php-file-formatting.general">
            <title>Général</title>

            <para>
                Pour les fichiers contenant uniquement du code PHP, la balise de fermeture
                ("?&gt;") n'est jamais permise. Il n'est pas requis par PHP. Ne pas l'inclure permet
                de se prémunir les problèmes liés à l'injection accidentelle d'espaces blancs dans
                la sortie.
            </para>

            <para>
                <emphasis>IMPORTANT :</emphasis> L'inclusion de données binaires arbitraires
                comme il est permis par <code>__HALT_COMPILER()</code> est prohibé dans tout fichier
                PHP de Zend Framework, ainsi que dans tout fichier dérivé. L'utilisation de cette
                possibilité est uniquement permise pour des scripts spéciaux d'installation.
            </para>
        </sect2>

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

            <para>Utilisez une indentation de 4 espaces, sans tabulations.</para>
        </sect2>

        <sect2 id="coding-standard.php-file-formatting.max-line-length">
            <title>Longueur maximum d'une ligne</title>

            <para>
                La longueur souhaitée d'une ligne est de 80 caractères, c'est-à-dire que les
                développeurs devraient avoir pour but de ne pas dépasser les 80 caractères pour des
                raisons pratiques. Cependant, des lignes plus longues sont acceptables. La longueur
                maximum de toute ligne de code PHP est de 120 caractères.
            </para>
        </sect2>

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

            <para>
                La terminaison de ligne est la terminaison standard pour les fichier textes
                UNIX. Les lignes doit finir seulement avec un "linefeed" (LF). Les linefeeds sont
                représentés comme 10 en ordinal, ou 0x0A en hexadécimal.
            </para>

            <para>
                Note : N'utilisez pas de retour chariots (CR) comme le font les Macintosh
                (0x0D) ou de combinaison retour chariot/linefeed (CRLF) comme le font les
                ordinateurs sous Windows (0x0D, 0x0A).
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.naming-conventions">
        <title>Conventions de nommage</title>

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

            <para>
                Zend Framework emploie une convention de nommage des classes où les noms des
                classes mènent directement dans les répertoires dans lesquels elles sont stockées.
                Le répertoire racine de Zend Framework est le répertoire "Zend/", tandis que le
                répertoire racine de la librairie extras de Zend Framework est "ZendX/". Toutes les
                classes sont stockées de façon hiérarchique sous ces dossiers racines.
            </para>

            <para>
                Les noms de classes ne peuvent contenir que des caractères alphanumériques.
                Les nombres sont autorisés, mais déconseillés. Les tirets bas ("_") ne sont
                autorisés que pour être utilisés comme séparateur de chemin ; le nom de fichier
                "Zend/Db/Table.php" doit mener à la classe appelée "Zend_Db_Table".
            </para>

            <para>
                Si un nom de classe comprend plus d'un mot, la première lettre de chaque
                nouveau mot doit être mis en majuscule. La mise en majuscule de lettres successives
                n'est pas autorisée, c'est-à-dire qu'une classe "Zend_PDF" est interdit alors que
                "Zend_Pdf" est autorisé.
            </para>

            <para>
                Ces conventions définissent un pseudo mécanisme d'espace de noms pour Zend
                Framework. Zend Framework adoptera la fonctionnalité des espaces de noms de PHP
                quand celle-ci sera disponible et qu'il sera possible pour les développeurs de
                l'utiliser dans leurs applications.
            </para>

            <para>
                Regardez les noms de classes dans les librairies standard et extras pour avoir
                des exemples de cette convention de nommage. <emphasis>IMPORTANT :</emphasis> le
                code qui opère avec le Framework mais qui n'en fait par partie, c'est-à-dire le code
                écrit par un utilisateur et pas Zend ou une des entreprises partenaires, ne doivent
                jamais commencer par "Zend_".
            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.filenames">
            <title>Noms de fichiers</title>

            <para>
                Pour tous les autres fichiers, seuls des caractères alphanumériques, tirets
                bas et tirets demi-cadratin ("-") sont autorisés. Les espaces et les caractères
                spéciaux sont interdits.
            </para>

            <para>
                Tout fichier contenant du code PHP doit se terminer par l'extension ".php".
                Ces exemples montrent des noms de fichiers acceptables pour contenir les noms de
                classes issus des exemples ci-dessus : <programlisting language="php"><![CDATA[
Zend/Db.php

Zend/Controller/Front.php

Zend/View/Helper/FormRadio.php
]]></programlisting>
                Les noms de fichiers doivent correspondre aux noms des classes décris ci-dessus.
            </para>
        </sect2>

        <sect2 id="coding-standard.naming-conventions.functions-and-methods">
            <title>Fonctions et méthodes</title>

            <para>
                Les noms de fonctions ne peuvent contenir que des caractères alphanumériques.
                Les tirets bas ("_") ne sont pas permis. Les nombres sont autorisés mais
                déconseillés.
            </para>

            <para>
                Les noms de fonctions doivent toujours commencer avec une lettre en minuscule.
                Quand un nom de fonction est composé de plus d'un seul mot, la première lettre de
                chaque mot doit être mise en majuscule. C'est ce que l'on appelle communément la
                "notationCamel".
            </para>

            <para>
                La clarté est conseillée. Le nom des fonctions devrait être aussi explicite
                que possible, c'est un gage de compréhension du code.
            </para>

            <para>
                Voici des exemples de noms acceptables pour des fonctions : <programlisting
                role="php"><![CDATA[
filterInput()

getElementById()

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

            <para>
                Pour la programmation orientée objet, les accesseurs aux objets doivent
                toujours être préfixés par soit "get" soit "set". Lorsque vous utilisez des motifs
                de conception, comme le Singleton ou la Fabrique, le nom de la méthode doit contenir
                le nom du motif pour permettre une reconnaissance plus simple et plus rapide du
                motif.
            </para>

            <para>
                Pour des méthodes d'objet qui sont déclarées avec la construction "private" ou
                "protected", le premier caractère du nom variable doit être un tiret bas simple
                ("_"). C'est la seule utilisation autorisé d'un tiret bas dans un nom de méthode.
                Les méthodes déclarées "public" ne devraient jamais commencer par un tiret
                bas.
            </para>

            <para>
                Les fonctions à portée globale ("les fonctions flottantes") sont autorisées
                mais déconseillées. Il est recommandé de mettre ces fonctions dans des classes
                statiques.
            </para>
        </sect2>

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

            <para>
                Les noms de variables ne peuvent contenir que des caractères alphanumériques.
                Les tirets bas ne sont pas permis. Les nombres sont autorisés mais
                déconseillés.
            </para>

            <para>
                Pour les variables membres de classe qui sont déclarées comme "private" ou
                "protected", le premier caractère du nom de la variable doit être un tiret bas
                simple ("_"). C'est la seule utilisation autorisé d'un tiret bas dans un nom de
                variable. Les variables membres "public" ne devraient jamais commencer par un tiret
                bas.
            </para>

            <para>
                Tout comme les noms de fonction (cf la section 3.3 ci-dessus), les noms de
                variables doivent toujours commencer par un caractère en minuscule et suivre la
                convention de capitalisation de la "notationCamel".
            </para>

            <para>
                La clarté est conseillée. Les variables devraient toujours être aussi claires
                que pratiques. Des noms de variables comme "$i" et "$n" sont déconseillé pour tout
                autre usage que les petites boucles. Si une boucle contient plus de 20 lignes de
                code, les variables pour les indices doivent avoir des noms descriptifs.
            </para>
        </sect2>

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

            <para>
                Les constantes peuvent contenir des caractères alphanumériques et des tirets
                bas. Les nombres sont autorisés.
            </para>

            <para>
                Les constantes doivent toujours être en majuscule, cependant les mots pouvant
                les composer doivent être séparés par des tiret-bats ("_").
            </para>

            <para>
                Par exemple, <code>EMBED_SUPPRESS_EMBED_EXCEPTION</code> est permis mais
                <code>EMBED_SUPPRESSEMBEDEXCEPTION</code> ne l'est pas.
            </para>

            <para>
                Les constantes doivent toujours être définies comme des membres d'une classe,
                en utilisant la construction "const". Définir des constantes globales avec "define"
                est permis mais déconseillé.
            </para>
        </sect2>
    </sect1>

    <sect1 id="coding-standard.coding-style">
        <title>Style de codage</title>

        <sect2 id="coding-standard.coding-style.php-code-demarcation">
            <title>Démarcation du code PHP</title>

            <para>
                Les codes PHP doivent toujours être délimités dans la forme complète, par les
                balises PHP standards : <programlisting language="php"><![CDATA[
<?php

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

            <para>
                Les balises courtes d'ouvertures ("&lt;?")ne sont pas autorisées. Pour les
                fichiers ne contenant que du code PHP, la balise de fermeture doit toujours être
                omise (Voir <xref linkend="coding-standard.php-file-formatting.general" />).
            </para>
        </sect2>

        <sect2 id="coding-standard.coding-style.strings">
            <title>Chaînes de caractères</title>

            <sect3 id="coding-standard.coding-style.strings.literals">
                <title>Chaînes littérales</title>

                <para>
                    Lorsqu'une chaîne est littérale (c'est-à-dire qu'elle ne contient pas de
                    substitution de variables), l'apostrophe ou guillemet simple doit être utilisé
                    pour démarquer la chaîne : <programlisting language="php"><![CDATA[
$a = 'Exemple de chaîne de caractères';
]]></programlisting>
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.strings.literals-containing-apostrophes">
                <title>Chaînes de caractères littérales avec apostrophes</title>

                <para>
                    Lorsque qu'une chaîne littérale contient des apostrophes, il est permis de
                    les démarquer en utilisant les guillemets doubles. Ceci est particulièrement
                    conseillé pour les requêtes SQL :
                    <programlisting language="php"><![CDATA[
$sql = "SELECT `id`, `name` from `people` "
     . "WHERE `name`='Eric' OR `name`='Caroline'";
]]></programlisting>
                    La syntaxe ci-dessus est préférée à l'échappement des apostrophes car elle
                    est plus facile à lire.
                </para>
            </sect3>

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

                <para>
                    La substitution des variables est permise en utilisant une de ces deux
                    formes : <programlisting language="php"><![CDATA[
$greeting = "Bonjour $name, bienvenue !";

$greeting = "Bonjour {$name}, bienvenue !";
]]></programlisting>
                </para>

                <para>
                    Pour des raisons d'uniformité, cette forme n'est pas permise :
                    <programlisting language="php"><![CDATA[
$greeting = "Bonjour ${name}, bienvenue !";
]]></programlisting>
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.strings.string-concatenation">
                <title>Concaténation de chaînes</title>

                <para>
                    Les chaînes peuvent êtres concaténées en utilisant l'opérateur ".". Un
                    espace doit toujours être ajouté avant, et après cet opérateur, cela permet
                    d'améliorer la lisibilité : <programlisting language="php"><![CDATA[
$company = 'Zend' . ' ' . 'Technologies';
]]></programlisting>
                </para>

                <para>
                    Lors de la concaténation de chaînes avec l'opérateur ".", il est permis de
                    couper le segment en plusieurs lignes pour améliorer la lisibilité. Dans ces
                    cas, chaque nouvelle ligne doit être remplie avec des espaces, de façon à
                    aligner le "." sous l'opérateur "=" : <programlisting language="php"><![CDATA[
$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Caroline' "
     . "ORDER BY `name` ASC ";
]]></programlisting>
                </para>
            </sect3>
        </sect2>

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

            <sect3 id="coding-standard.coding-style.arrays.numerically-indexed">
                <title>Tableaux indexés numériquement</title>

                <para>L'utilisation d'indices négatifs n'est pas permise.</para>

                <para>
                    Un tableau indexé peut commencer avec n'importe quel nombre positif,
                    cependant cette méthode est déconseillée. Il est conseillé de commencer
                    l'indexation à 0.
                </para>

                <para>
                    Lors de la déclaration de tableaux indexés avec la construction
                    <code>array</code>, un espace doit être ajouté après chaque virgule délimitante,
                    pour améliorer la lisibilité : <programlisting language="php"><![CDATA[
$sampleArray = array(1, 2, 3, 'Zend', 'Studio');
]]></programlisting>
                </para>

                <para>
                    Il est aussi permis de déclarer des tableaux indexés sur plusieurs lignes
                    en utilisant la construction <code>array</code>. Dans ce cas, chaque nouvelle
                    ligne doit être remplie par des espaces jusqu'à ce que cette ligne s'aligne,
                    comme il est montré dans l'exemple suivant :
                    <programlisting language="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>Tableaux associatifs</title>

                <para>
                    Lorsque de la déclaration de tableaux associatifs avec la construction
                    <code>array</code>, il est conseillé de séparer la définition sur plusieurs
                    lignes. Dans ce cas, chaque ligne successive doit être remplie par des espaces
                    pour que les clés et les valeurs soient alignées : <programlisting
                    role="php"><![CDATA[
$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');
]]></programlisting>
                </para>
            </sect3>
        </sect2>

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

            <sect3 id="coding-standard.coding-style.classes.declaration">
                <title>Déclaration de classes</title>

                <para>
                    Les classes doivent être nommées conformément aux conventions de nommage
                    de Zend Framework.
                </para>

                <para>
                    L'accolade est toujours écrite dans la ligne sous le nom de la
                    classe.
                </para>

                <para>
                    Toutes les classes doivent avoir un bloc de documentation conforme aux
                    standards PHPDocumentor.
                </para>

                <para>Tout code d'une classe doit être indenté avec 4 espaces.</para>

                <para>Une seule classe est permise par fichier PHP.</para>

                <para>
                    Le placement de code additionnel dans un fichier de classe est permis,
                    mais déconseillé. Dans ces fichiers, deux lignes vides doivent séparer la classe
                    du code PHP additionnel.
                </para>

                <para>
                    Voici un exemple d'une déclaration de classe autorisée : <programlisting
                    role="php"><![CDATA[
/**
 * Bloc de documentation
 */
class SampleClass
{
    // contenu de la classe
    // qui doit être indenté avec 4 espaces
}
]]></programlisting>
                </para>
            </sect3>

            <sect3 id="coding-standard.coding-style.classes.member-variables">
                <title>Variables membres de la classe</title>

                <para>
                    Les variables membres doivent être nommées en respectant les conventions
                    de nommage de Zend Framework.
                </para>

                <para>
                    Toute variable déclarée dans une classe doit être listée en haut de cette
                    classe, avant toute déclaration de méthode.
                </para>

                <para>
                    La construction <code>var</code> n'est pas permise. Les variables membres
                    déclarent toujours leur visibilité en utilisant la construction
                    <code>private</code>, <code>protected</code>, ou <code>public</code>. L'accès
                    direct à ces variables membres en les rendant publiques est permis mais
                    déconseillé. Il est préférable d'utiliser des accesseurs (set/get).
                </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.functions-and-methods">
            <title>Fonctions et méthodes</title>

            <sect3 id="coding-standard.coding-style.functions-and-methods.declaration">
                <title>Déclaration de fonctions et de méthodes</title>

                <para>
                    Les fonctions doivent être nommées en respectant les conventions de
                    nommage de Zend Framework.
                </para>

                <para>
                    Les fonctions internes aux classes doivent toujours déclarer leur
                    visibilité en utilisant la construction <code>private</code>,
                    <code>protected</code>, ou <code>public</code>.
                </para>

                <para>
                    Tout comme les classes, l'accolade ouvrante est toujours écrite sous le
                    nom de la fonction. Il n'y a pas d'espace entre le nom de la fonction et les
                    parenthèses des arguments. Il n'y a pas d'espace entre la parenthèse fermante et
                    l'accolade.
                </para>

                <para>Les fonctions globales sont fortement déconseillées.</para>

                <para>
                    Voici un exemple d'une déclaration permise d'une fonction de classe :
                    <programlisting language="php"><![CDATA[
/*
 * Bloc de documentation
 */
class Foo
{
    /**
     * Bloc de documentation
     */
    public function bar()
    {
        // contenu de la fonction
        // qui doit être indenté avec 4 espaces
    }
}
]]></programlisting>
                </para>

                <para>
                    <emphasis>NOTE :</emphasis> Le passage par référence est permis uniquement
                    dans la déclaration de la fonction : <programlisting language="php"><![CDATA[
/**
 * Bloc de documentation
 */
class Foo
{
    /**
     * Bloc de documentation
     */
    public function bar(&$baz)
    {}
}
]]></programlisting>
                </para>

                <para>L'appel par référence est interdit.</para>

                <para>
                    La valeur de retour ne doit pas être entourée de parenthèses. Ceci peut
                    gêner à la lecture et peut aussi casser le code si une méthode est modifiée plus
                    tard pour retourner par référence. <programlisting language="php"><![CDATA[
/**
 * Bloc de documentation
 */
class Foo
{
    /**
     * INCORRECT
     */
    public function bar()
    {
        return($this->bar);
    }

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

            <sect3 id="coding-standard.coding-style.functions-and-methods.usage">
                <title>Usage de fonctions et méthodes</title>

                <para>
                    Les arguments d'une fonction sont séparés par un espace après la virgule
                    de délimitation. Voici un exemple d'un appel de fonction qui prend trois
                    arguments : <programlisting language="php"><![CDATA[
threeArguments(1, 2, 3);
]]></programlisting>
                </para>

                <para>
                    L'appel par référence est interdit. Référez vous à la section sur la
                    déclaration de fonctions pour la méthode correcte de passage des argument par
                    référence.
                </para>

                <para>
                    Pour les fonctions dont les arguments peuvent être des tableaux, l'appel à
                    la fonction doit inclure la construction "array" et peut être divisé en
                    plusieurs ligne pour améliorer la lecture. Dans ces cas, les standards
                    d'écriture de tableaux s'appliquent aussi : <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);
]]></programlisting>
                </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standard.coding-style.control-statements">
            <title>Structure de contrôle</title>

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

                <para>
                    Les structure de contrôles basées sur les constructions <code>if</code> et
                    <code>elseif</code> doivent avoir un seul espace avant la parenthèse ouvrante de
                    la condition, et un seul espace après la parenthèse fermante.
                </para>

                <para>
                    Pour la condition entre les parenthèses, les opérateurs doivent être
                    séparés par des espaces pour une meilleure lisibilité. Les parenthèses internes
                    sont conseillées pour améliorer le regroupement logique de longues
                    conditions.
                </para>

                <para>
                    L'accolade ouvrante est écrite sur la même ligne que la condition.
                    L'accolade fermante est toujours écrite sur sa propre ligne. Tout contenu
                    présent à l'intérieur des accolades doit être indenté par 4 espaces.
                    <programlisting language="php"><![CDATA[
if ($a != 2) {
    $a = 2;
}
]]></programlisting>
                </para>

                <para>
                    Pour les instruction "if" qui incluent "elseif" ou "else", les conventions
                    de formatage sont similaires à celles de la construction "if". Les exemples
                    suivants montrent le formatage approprié pour les structures "if" avec "else"
                    et/ou les constructions "elseif" : <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;
}
]]></programlisting>
                    PHP permet que ces instructions soient écrites sans accolades dans
                    certaines circonstances. La convention de codage ne fait pas de différentiation
                    et toutes les instructions "if", "elseif" et "else" doivent utiliser des
                    accolades.
                </para>

                <para>
                    L'utilisation de la construction "elseif" est permise mais fortement
                    déconseillée au profit de la combinaison "else if".
                </para>
            </sect3>

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

                <para>
                    Les instructions de contrôle avec "switch" ne doivent avoir qu'un seul
                    espace avant la parenthèse ouvrante de l'instruction conditionnelle, et aussi un
                    seul espace après la parenthèse fermante.
                </para>

                <para>
                    Tout le contenu à l'intérieur de l'instruction "switch" doit être indenté
                    avec 4 espaces. Le contenu sous chaque "case" doit être indenté avec encore 4
                    espaces supplémentaires.
                </para>

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

    case 2:
        break;

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

                <para>
                    La construction <code>default</code> ne doit jamais être oubliée dans une
                    instruction <code>switch</code>.
                </para>

                <para>
                    <emphasis>NOTE :</emphasis> Il est parfois pratique d'écrire une clause
                    <code>case</code> qui passe à travers le <code>case</code> suivant en omettant
                    l'inclusion de <code>break</code> ou <code>return</code>. Pour distinguer ce cas
                    d'un bug, toute clause <code>case</code> ne contenant pas <code>break</code> ou
                    <code>return</code> doit contenir le commentaire "// break intentionally
                    omitted".
                </para>
            </sect3>
        </sect2>

        <sect2 id="coding-standards.inline-documentation">
            <title>Documentation intégrée</title>

            <sect3 id="coding-standards.inline-documentation.documentation-format">
                <title>Format de la documentation</title>

                <para>
                    Tous les blocs de documentation ("docblocks") doivent être compatible avec
                    le format phpDocumentor. La description du format phpDocumentor n'est pas du
                    ressort de ce document. Pour plus d'information, visitez <ulink
                    url="http://phpdoc.org/">http://phpdoc.org/</ulink>
                </para>

                <para>
                    Tous les fichiers de code source écrits pour Zend Framework ou qui opèrent
                    avec ce framework doivent contenir un docblock du fichier, en haut de chaque
                    fichier, et un docblock de classe immédiatement au dessus de chaque classe.
                    Ci-dessous vous trouverez des exemples de tels docblocs.
                </para>
            </sect3>

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

                <para>
                    Chaque fichier qui contient du code PHP doit avoir un bloc d'entête en
                    haut du fichier qui contient au minimum ces balises phpDocumentor :
                    <programlisting language="php"><![CDATA[
/**
 * Description courte du fichier
 *
 * Description longue du fichier s'il y en a une
 *
 * LICENSE: Informations sur la licence
 *
 * @copyright  2008 Zend Technologies
 * @license    http://framework.zend.com/license   BSD License
 * @version    $Id:$
 * @link       http://framework.zend.com/package/PackageName
 * @since      File available since Release 1.5.0
*/
]]></programlisting>
                </para>
            </sect3>

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

                <para>
                    Chaque classe doit avoir un docblock qui contient au minimum ces balises
                    phpDocumentor : <programlisting language="php"><![CDATA[
/**
 * Description courte de la classe
 *
 * Description longue de la classe, s'il y en a une
 *
 * @copyright  2008 Zend Technologies
 * @license    http://framework.zend.com/license   BSD License
 * @version    Release: @package_version@
 * @link       http://framework.zend.com/package/PackageName
 * @since      Class available since Release 1.5.0
 * @deprecated Class deprecated in Release 2.0.0
 */
]]></programlisting>
                </para>
            </sect3>

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

                <para>
                    Chaque fonction, méthode, doit avoir un docblock contenant au minimum :
                    <itemizedlist>
                        <listitem>
                            <para>Une description de la fonction</para>
                        </listitem>

                        <listitem>
                            <para>Tous les arguments</para>
                        </listitem>

                        <listitem>
                            <para>Toutes les valeurs de retour possibles</para>
                        </listitem>
                    </itemizedlist>
                </para>

                <para>
                    Il n'est pas nécessaire d'utiliser la balise "@access" parce que le niveau
                    d'accès est déjà connu avec les constructions "public", "private", "protected"
                    utilisée pour déclarer la fonction.
                </para>

                <para>
                    Si une fonction/méthode peut lancer une exception, utilisez "@throws" :
                    <programlisting language="php"><![CDATA[
@throws exceptionclass [description]
]]></programlisting>
                </para>
            </sect3>
        </sect2>
    </sect1>
</appendix>