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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 13549 -->
<!-- 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 role="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 role="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 role="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 role="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
                role="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
                role="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
                role="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 role="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
                role="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
                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>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
                role="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 role="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
                role="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 role="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 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>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 role="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 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 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 role="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 role="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 role="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
                role="php"><![CDATA[
@throws exceptionclass [description]
]]></programlisting></para>
            </sect3>
        </sect2>
    </sect1>
</appendix>