[PHP-DOC] cvs: phpdoc /fr/pear standards.xml

[Damien Seguy]

dams            Fri Mar 30 00:51:52 2001 EDT

  Added files:                 
    /phpdoc/fr/pear     standards.xml 
  Log:
  Added PEAR and translated.
  

Index: phpdoc/fr/pear/standards.xml
+++ phpdoc/fr/pear/standards.xml
 <chapter id="pear.standards">
  <title>Style de codage PEAR</title>
  <sect1 id="pear.standards.indenting">
   <title>Indenting</title>
   <para>
    Utilisez une indentation de 4 espaces, mais pas de tabulations.
    Si vous utilisez Emacs pour &eacute;diter du code PEAR, pensez &agrave; mettre
    indent-tabs-mode &agrave; nil. Voici un exemple de hook qui
    va configurer Emacs suivant ces conseils (you devez vous
    assurer qu'il sera appel&eacute; avant l'&eacute;dition des fichiers PHP) : 
    <programlisting role="elisp">
(defun php-mode-hook ()
  (setq tab-width 4
        c-basic-offset 4
        c-hanging-comment-ender-p nil
        indent-tabs-mode nil))
</programlisting>
   </para>
   <para>
    Voici quelques r&egrave;gles pour vim : 
    <programlisting role="vim">
  set expandtab 
  set shiftwidth=4 
  set tabstop=4 
    </programlisting>
   </para>
  </sect1>
  <sect1 id="pear.standards.control">
   <title>Structures de contr&ocirc;le</title>
   <para>
    Cela couvre if, for, while, switch, etc... Voici un exemple de
    condition if, (c'est une des plus compliqu&eacute;es) : 
    <programlisting role="php">
if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) &amp;&amp; (condition4)) {
    action2;
} else {
    defaultaction;
}
</programlisting>
   </para>
   <simpara>
    Les structures de contr&ocirc;le doivent &ecirc;tre suivi d'un espace
    et d'une parenth&egrave;se ouvrante, pour les distinguer des appels
    de fonctions.
   </simpara>
   <simpara>
    Il est vivement recommand&eacute; d'utiliser les accolades en
    toutes occasions, m&ecirc;me lorsqu'elles sont techniquement
    optionnelles. Cela am&eacute;liore nettement la lisibilit&eacute;, et
    r&eacute;duit la probabilit&eacute; d'erreurs lorsque de nouvelles
    lignes sont ajout&eacute;es.
   </simpara>
   <para>
    Boucle For, switch:
     <programlisting role="php">
switch (condition) {
case 1:
    action1;
    break;

case 2:
    action2;
    break;

default:
    defaultaction;
    break;

}
</programlisting>
   </para>
  </sect1>
  <sect1 id="pear.standards.funcalls">
   <title>Function Calls</title>
   <para>
    Les fonctions doivent &ecirc;tre appel&eacute;es sans espaces entre le nom
    de la fonction, la parenth&egrave;se ouvrante et le premier argument;
    il faut place un espace entre chaque argument et la virgule
    de s&eacute;paration, mais pas d'espace entre le dernier argument,
    la parenth&egrave;se fermante et le point-virgule. Voici un exemple : 
    <programlisting role="php">
$var = foo($bar, $baz, $quux);
</programlisting>
   </para>
   <para>
    Comme illustr&eacute; ci-dessus, il faut un espace autour des signes
    &eacute;gal lorsqu'il est utilis&eacute; dans une assignation de variable.
    Dans le cas d'assignement en bloc, plusieurs espaces peuvent &ecirc;tre
    introduit pour am&eacute;liorer la lisibilit&eacute;.
    <programlisting role="php">
$short         = foo($bar);
$long_variable = foo($baz);
</programlisting>
   </para>
  </sect1>
  <sect1 id="pear.standards.funcdef">
   <title>Function Definitions</title>
   <para>
    Les d&eacute;clarations de fonction suivent la convention 
    "one TRUE brace" (une seule accolade v&eacute;ritable) : 
    <programlisting role="php">
function fooFunction($arg1, $arg2 = '')
{
    if (condition) {
        statement;
    }
    return $val;
}
</programlisting>
   </para>
   <para>
    Les arguments ayant une valeur par d&eacute;faut doivent aller
    &agrave; la fin de la liste des arguments. Essayez de retourner
    une valeur utile de vos fonctions, d&egrave;s que c'est le cas.
    Voici un exemple : 
    <programlisting role="php">
function connect(&amp;$dsn, $persistent = false)
{
    if (is_array($dsn)) {
        $dsninfo = &amp;$dsn;
    } else {
        $dsninfo = DB::parseDSN($dsn);
    }
    
    if (!$dsninfo || !$dsninfo['phptype']) {
        return $this->raiseError();
    }
    
    return true;
}
    </programlisting>
   </para>
  </sect1>
  <sect1 id="pear.standards.comments">
   <title>Commentaires</title>
   <para>
    La documentation du code doit suivre les conventions de
    PHPDoc, similaire &agrave; Javadoc. Plus d'informations sur PHPDoc
    sont disponibles ici : <ulink url="&url.phpdoc;">&url.phpdoc;</ulink>.
   </para>
   <para>
    Les commentaires hors documentation sont vivement conseill&eacute;s.
    En r&egrave;gle g&eacute;n&eacute;aral, si vous voyez une portion de code et que 
vous
    pensez "Houla!, je n'ai pas envie de tester &ccedil;a", vous devez
    la commentez avant d'oublier ce qu'elle fait.
   </para>
   <para>
    Les commentaires de style C (/* */) et standard C++ (// ) sont
    bien tous les deux. Les autres styles (notamment Perl et shell
    (# )) sont d&eacute;conseill&eacute;s.
   </para>
  </sect1>
  <sect1 id="pear.standards.including">
   <title>Inclusion de Code</title>
   <para>
    A chaque fois que vous incluez inconditionnellement une
    classe, utilisez la fonction <function>require_once</function>.
    A chaque fois que vous incluez conditionnellement une
    classe, utilisez la fonction <function>include_once</function>.
    Ces deux fonctions s'assureront que les classes ne sont 
    d&eacute;clar&eacute;es qu'une seule fois. Elles partagent la m&ecirc;me
    liste de fichier, ce qui permet leur utilisation sans
    g&ecirc;ne. Un fichier inclus par <function>require_once</function>
    ne sera pas inclus encore une fois avec <function>include_once</function>.
    <note>
     <simpara>
      <function>include_once</function> et
      <function>require_once</function> sont des commandes, et pas
      des fonctions. Vous n'&ecirc;tes pas oblig&eacute;s d'utiliser des 
      parenth&egrave;ses autour des noms de fichiers.
     </simpara>
    </note>
   </para>    
  </sect1>

  <sect1 id="pear.standards.tags">
   <title>Balises de code PHP</title>
   <para>
    Utilisez <emphasis>toujours</emphasis> la syntaxe 
    <literal>&lt;?php ?&gt;</literal> pour d&eacute;limiter du 
    code PHP, et jamais <literal>&lt;? ?&gt;</literal>.
    Ceci est n&eacute;cessaire pour la compatibilit&eacute; du code PEAR et c'est
    la version la plus portable du code PHP sur les diff&eacute;rents
    syst&egrave;mes d'exploitation.
   </para>
  </sect1>

  <sect1 id="pear.standards.header">
   <title>Ent&ecirc;te de fichier</title>
   <para>
    Tous les codes sources des distributions PEAR doivent contenir
    les commentaires suivants comme ent&ecirc;te : 
    <programlisting role="php">
/* vim: set expandtab tabstop=4 shiftwidth=4: */
// +----------------------------------------------------------------------+
// | PHP version 4.0                                                      |
// +----------------------------------------------------------------------+
// | Copyright (c) 1997, 1998, 1999, 2000, 2001 The PHP Group             |
// +----------------------------------------------------------------------+
// | This source file is subject to version 2.0 of the PHP license,       |
// | that is bundled with this package in the file LICENSE, and is        |
// | available at through the world-wide-web at                           |
// | http://www.php.net/license/2_02.txt.                                 |
// | If you did not receive a copy of the PHP license and are unable to   |
// | obtain it through the world-wide-web, please send a note to          |
// | [EMAIL PROTECTED] so we can mail you a copy immediately.               |
// +----------------------------------------------------------------------+
// | Authors: Original Author &lt;[EMAIL PROTECTED]>                     |
// |          Your Name &lt;[EMAIL PROTECTED]>                              |
// +----------------------------------------------------------------------+
//
// &dollar;Id&dollar;
</programlisting>
   </para>
   <para>   
    Il n'y a pas de r&egrave;gle fixe pour d&eacute;terminer &agrave; quel moment un
    contributeur doit &ecirc;tre ajout&eacute; dans la liste des auteurs d'un fichier
    source. En g&eacute;n&eacute;ral, les modifications doivent &ecirc;tre 
substancielle
    (environs 10 &agrave; 20% du code initial). Des d&eacute;rogations peuvent 
&ecirc;tre
    donn&eacute;es pour les r&eacute;&eacute;critures compl&egrave;tes de fonctions, 
ou les 
    contributions &agrave; de nouvelles logiques d'utilisation.
   </para>
   <para>
    La simple r&eacute;organisation de code ou les corrections de 
    bug ne justifie pas l'ajout d'un contributeur dans la liste
    des auteurs.
   </para>
   <para>
    Les fichiers qui ne font pas partie de la biblioth&egrave;que de base
    PEAR doivent avoir un bloc comparable &agrave; celui cit&eacute; ci-dessus,
    indiquant le copyright, la licence et les auteurs. Tous les
    fichiers devraient inclure une description du mod&egrave;le suivi, pour
    am&eacute;liorer la coh&eacute;rence de l'ensemble.
   </para>
  </sect1>

  <sect1 id="pear.standards.cvstags">
   <title>CVS Tags</title>
   <para>
    Ajoutez le signe &dollar;Id&dollar; (CVS vendor tag) dans chaque fichier.
    Dans chaque fichier que vous &eacute;ditez, pensez &agrave; l'ajouter s'il n'est 
pas
    pr&eacute;sent (ou remplacez les anciennes valeurs telles que "Last Modified:", 
etc.).
    <note>
     <simpara>
      Nous avons une marque $Horde dans le CVS Horde pour suivre nos
      versions s&eacute;par&eacute;ment. Nous pouvons faire la m&ecirc;me chose avec 
une
      marque $PEAR, qui resterait m&ecirc;me si les fichiers PEAR migrent sur
      un autre syst&egrave;me de suivi de version.
     </simpara>
    </note>
   </para>
  </sect1>

  <sect1 id="pear.standards.exampleurls">
   <title>URL d'example</title>
   <para>
    Utilisez "example.com" pour tous les exemples, comme sp&eacute;cifi&eacute; dans
    la RFC 2606.
   </para>
  </sect1>

  <sect1 id="pear.standards.constants">
   <title>Noms des constantes</title>
   <para>
    Les constantes doivent toujours &ecirc;tre en majuscule, les mots &eacute;tant 
s&eacute;par&eacute;s
    par des soulign&eacute;s (_). Pr&eacute;fixez les constantes avec le nom 
    de la classe ou du package dont elles font parties. Par exemple,
    les constantes utilis&eacute;es dans le package 
    <literal>DB::</literal> commencent toutes par "<literal>DB_</literal>".
   </para>
  </sect1>
  
 </chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->