Ces quelques règles de base concernant le style de codage dans l'application sont directement issues du PEAR coding-style.
Utilisez une indentation de 4 espaces, mais pas de tabulations. Si vous utilisez Emacs pour éditer du code PEAR, pensez à mettre indent-tabs-mode à nil. Voici un exemple de hook qui va configurer Emacs suivant ces conseils (vous devez vous assurer qu'il sera appelé avant l'édition des fichiers PHP) :
(defun php-mode-hook () (setq tab-width 4 c-basic-offset 4 c-hanging-comment-ender-p nil indent-tabs-mode nil))
Voici quelques règles pour vim :
set expandtab
set shiftwidth=4
set tabstop=4
Cela couvre if, for, while, switch, etc... Voici un exemple de condition if, (c'est une des plus compliquées) :
if ((condition1) || (condition2)) {
action1;
} elseif ((condition3) && (condition4)) {
action2;
} else {
defaultaction;
}
Les structures de contrôle doivent être suivi d'un espace et d'une parenthèse ouvrante, pour les distinguer des appels de fonctions.
Il est vivement recommandé d'utiliser les accolades en toutes occasions, même lorsqu'elles sont techniquement optionnelles. Cela améliore nettement la lisibilité, et réduit la probabilité d'erreurs lorsque de nouvelles lignes sont ajoutées.
Boucle For, switch :
switch (condition) {
case 1:
action1;
break;
case 2:
action2;
break;
default:
defaultaction;
break;
}
Les fonctions doivent être appelées sans espaces entre le nom de la fonction, la parenthèse ouvrante et le premier argument; il faut place un espace entre chaque argument et la virgule de séparation, mais pas d'espace entre le dernier argument, la parenthèse fermante et le point-virgule. Voici un exemple :
$var = foo($bar, $baz, $quux);
Comme illustré ci-dessus, il faut un espace autour des signes égal lorsqu'il est utilisé dans une assignation de variable. Dans le cas d'assignation en bloc, plusieurs espaces peuvent être introduit pour améliorer la lisibilité.
<?php
$short = foo($bar);
$long_variable = foo($baz);
?>
Les déclarations de fonction suivent la convention "one TRUE brace" (une seule accolade véritable) :
<?php
function fooFunction($arg1, $arg2 = '')
{
if (condition) {
statement;
}
return $val;
}
?>
Les arguments ayant une valeur par défaut doivent aller à la fin de la liste des arguments. Essayez de retourner une valeur utile de vos fonctions, dès que c'est le cas. Voici un exemple :
<?php
function connect(&$dsn, $persistent = FALSE)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}
if (!$dsninfo || !$dsninfo['phptype']) {
return $this->raiseError();
}
return TRUE;
}
?>
La documentation du code doit suivre les conventions de PHPDoc, similaire à Javadoc. Plus d'informations sur PHPDoc sont disponibles ici : http://www.phpdoc.de/.
Les commentaires hors documentation sont vivement conseillés. En règle généaral, si vous voyez une portion de code et que vous pensez "Houla!, je n'ai pas envie de tester ça", vous devez la commentez avant d'oublier ce qu'elle fait.
Les commentaires de style C (/* */) et standard C++ (// ) sont bien tous les deux. Les autres styles (notamment Perl et shell (# )) sont déconseillés.
A chaque fois que vous incluez inconditionnellement une classe, utilisez la fonction require_once(). A chaque fois que vous incluez conditionnellement une classe, utilisez la fonction include_once(). Ces deux fonctions s'assureront que les classes ne sont déclarées qu'une seule fois. Elles partagent la même liste de fichier, ce qui permet leur utilisation sans gêne. Un fichier inclus par require_once() ne sera pas inclus encore une fois avec include_once().
Note : include_once() et require_once() sont des commandes, et pas des fonctions. Vous n'êtes pas obligés d'utiliser des parenthèses autour des noms de fichiers.
Important. Il ne faut pas inclure de fichiers externes dans les fichiers de définition de classes. Cela rend plus complexe la réutilisation du code et nous avons donc banni ce procédé
Utilisez toujours la syntaxe pour délimiter du code PHP, et jamais . Ceci est nécessaire pour la compatibilité du code PEAR et c'est la version la plus portable du code PHP sur les différents systèmes d'exploitation.
Tous les codes sources des distributions PEAR doivent contenir les commentaires suivants comme entête :
/* 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 | // | license@php.net so we can mail you a copy immediately. | // +----------------------------------------------------------------------+ // | Authors: Original Author <author@example.com> | // | Your Name <you@example.com> | // +----------------------------------------------------------------------+ // // $Id: coding-style.html,v 1.2 2005-05-12 08:06:47 gautier Exp $
Il n'y a pas de règle fixe pour déterminer à quel moment un contributeur doit être ajouté dans la liste des auteurs d'un fichier source. En général, les modifications doivent être substancielle (environs 10 à 20% du code initial). Des dérogations peuvent être données pour les réécritures complètes de fonctions, ou les contributions à de nouvelles logiques d'utilisation.
La simple réorganisation de code ou les corrections de bug ne justifie pas l'ajout d'un contributeur dans la liste des auteurs.
Les fichiers qui ne font pas partie de la bibliothèque de base PEAR doivent avoir un bloc comparable à celui cité ci-dessus, indiquant le copyright, la licence et les auteurs. Tous les fichiers devraient inclure une description du modèle suivi, pour améliorer la cohérence de l'ensemble.
Ajoutez le signe $Id: coding-style.html,v 1.2 2005-05-12 08:06:47 gautier Exp $ (CVS vendor tag) dans chaque fichier. Dans chaque fichier que vous éditez, pensez à l'ajouter s'il n'est pas présent (ou remplacez les anciennes valeurs telles que "Last Modified:", etc.).
Note : Nous avons une marque $Horde dans le CVS Horde pour suivre nos versions séparément. Nous pouvons faire la même chose avec une marque $PEAR, qui resterait même si les fichiers PEAR migrent sur un autre système de suivi de version.
Utilisez "example.com" pour tous les exemples, comme spécifié dans la RFC 2606
Les constantes doivent toujours être en majuscule, les mots étant séparés par des soulignés (_). Préfixez les constantes avec le nom de la classe ou du package dont elles font parties. Par exemple, les constantes utilisées dans le package DB:: commencent toutes par "DB_".