Table des matières
Il est important d'être cohérent, surtout lorsque l'on écrit du code open-source, car ce code appartient en définitive à des millions de personnes, et que la résolution des bugs repose en grande partie sur ces personnes pour repérer les problèmes et comprendre comment les résoudre.
C'est pourquoi, lorsque vous écrivez du code pour PrestaShop, que ce soit pour un thème, un module ou une modification du coeur du logiciel, vous devez faire en sorte de suivre les indications qui suivent. Elles sont déjà suivies par les développeurs de PrestaShop, et les suivre également est la manière la plus sûr de voir votre code s'intégrer dans PrestaShop de manière élégante.
Pour résumer, la cohérence du code permet de s'assurer que celui-ci est lisible et facile à maintenir.
Si vous utilisez un éditeur, vous pouvez utiliser le validateur CodeSniffer pour vous aider à mieux écrire votre code.
Tout comme le nom des classes, des méthodes et des fonctions, le nom des variables doit toujours être écrit en anglais, afin d'être compréhensible par le plus grand nombre.
Utilisez des caractères minuscules, et séparez les mots par des caractères soulignés. N'utilisez jamais le format camelCase.
$my_var
.$my_var
.private $my_var
.$my_var = 17; $a = $b; |
"+
", "-
", "*
", "/
", "=
" et toute combinaison de ces opérateurs (ex. : "/=
") doivent avoir une espace avant et après.
$a + 17; $result = $b / 2; $i += 34; |
".
" doit ne pas avoir d'espace avant ou après.
echo $a.$b; $c = $d.$this->foo(); |
Pour des raisons de performance, n'abusez pas des concaténations. |
".=
" doit avoir une espace avant et après.
$a .= 'Debug'; |
Lorsque vous testez une variable booléenne (true/false), n'utilisez pas a opérateur de comparaison, mais testez directement la valeur elle-même, ou la valeur préfixe d'un point d'exclamation :
// ne faites pas ceci if ($var == true) // ...ni ceci if ($var == false) // faites ceci if ($var) // ...ou ceci if (!$var) |
if
, elseif
, while
, for
: doivent recevoir une espace entre le mot-clé et les parenthèses :
if (<condition>) while (<condition>) |
Lorsque vous utilisez une combinaison de if
et de else
, et que chacun renvoie une valeur, le else
peut être omis :
if (<condition>) return false; return true; |
Nous vous recommandons de n'utiliser qu'un |
Lorsqu'une méthode ou une fonction renvoie un booléen (true
/false
) et que méthode/fonction en cours dépend de sa valeur, la déclaration if peut être omise :
public aFirstMethod() { return $this->aSecondMethod(); } |
Les tests doivent être groupés par entité :
if ($price AND !empty($price)) ... if (!Validate::$myObject OR $myObject->id === NULL) ... |
L'ordre des propriétés de la méthode doit être ainsi : visibility static function functionName()
.
private static function foo() |
Le nom des méthodes et fonctions doivent utiliser la méthode CamelCase : commencer par un caractère en minuscule, chaque mot suivant doit commencer par un caractère en majuscule :
public function myExampleMethodWithALotOfWordsInItsName() |
Les accolades qui ouvrent le code d'une méthode doit être précédé d'un retour à la ligne :
public function myMethod($arg1, $arg2) { ... } |
Le nom des méthodes et fonctions doit être explicite ; les noms tels que b()
ou ef()
sont donc à proscrire :
Les seules exceptions admises sont la fonction de traduction (nommée |
Les virgules doivent être suivies (et non précédées) d'une espace :
protected function myProtectedMethod($arg1, $arg2, $arg3 = null) |
Le nom d'un objet doit être au singulier :
class Customer |
Le nom d'une classe doit suivre la norme CamelCase, sauf pour la première lettre qui doit être en majuscule :
class MyBeautifulClass |
true
, false
et null
qui doivent être en minuscule : ENT_NOQUOTE
, true
.Le nom des constantes doit être préfixé avec "PS_
" dans un module ou le coeur de PrestaShop :
define('PS_DEBUG', 1); define('PS_MODULE_NAME_DEBUG', 1); |
_
".Tous les mots-clés doivent être en minuscule : as, case, if, echo, null
.
Les variables de configuration doivent suivre les mêmes règles que celles définies ci-dessus.
Une chaîne doit être entourée de guillemets droits simples ('
), et non de guillemets droits doubles ("
) :
echo 'Debug'; $myObj->name = 'Hello '.$name; |
//
" est autorisé.Il doit y avoir une espace à l'ouverture d'un signe de commentaire "//
" :
// My great comment |
Le marqueur de commentaire "//
" est toléré à la fin d'une ligne de code :
$a = 17 + 23; // A comment inside my example function |
En dehors des fonctions et méthodes, seuls les marqueurs "/*
" and "*/
" sont autorisés :
/* This method is required for compatibility issues */ public function foo() { // Some code explanation right here ... } |
Un commentaire phpDoc est requis en ouverture de méthode :
/** * Return field value if possible (both classical and multilingual fields) * * Case 1: Return value if present in $_POST / $_GET * Case 2: Return object value * * @param object $obj Object * @param string $key Field name * @param integer $id_lang Language id (optional) * @return string */ protected function getFieldValue($obj, $key, $id_lang = NULL) |
Pour plus d'information sur la syntaxe phpDoc : http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html. |
La déclaration return
ne nécessaire pas de parenthèses, sans de le cas d'une expression composée :
return $result; return ($a + $b); return (a() - b()); return true; |
La déclaration return
peut être utilisée pour sortir d'une méthode :
return; |
Il est interdit d'appeler une fonction précédée d'un "@
", mais faites attention aux appels de fonctions/méthodes qui ont un identifiant/mot de passe ou un chemin dans leurs arguments :
myfunction(); // Dans l'exemple suivant, nous utilisons @ pour des raisons de sécurité @mysql_connect(...); |
Il doit y avoir une ligne vide après la balise d'ouverture de PHP :
<?php require_once('my_file.inc.php'); |
\t
" est le seul caractère d'indentation autorisé.Chaque niveau d'indentation doit utiliser un seul caractère d'indentation :
function foo($a) { if ($a == null) return false; ... } |
Le mot-clé array
ne doit pas être suivi d'une espace :
array(17, 23, 42); |
Lorsqu'il y a trop de données dans un tableau, l'indentation doit être comme suit :
$a = array( 36 => $b, $c => 'foo', $d => array(17, 23, 42), $e => array( 0 => 'zero', 1 => $one ) ); |
Les accolades sont à éviter lorsqu'elles n'encadrent qu'un seule instruction ou une combinaison de déclarations :
if (!$result) return false; for ($i = 0; $i < 17; $i++) if ($myArray[$i] == $value) $result[] = $myArray[$i]; else $failed++; |
Toutes les données en provenance de l'utilisateur doivent être typées :
$data = Tools::getValue('name'); $myObject->street_number = (int)Tools::getValue('street_number'); |
Tous les paramètres de méthodes/fonctions doivent être typés (avec Array
ou Object
) dès récupération :
public myMethod(Array $var1, $var2, Object $var3) |
Tous les autres paramètres doivent être typés à chaque utilisation, sauf quand ils sont envoyés à d'autres méthodes/fonctions :
protected myProtectedMethod($id, $text, $price) { $this->id = (int)$id; $this->price = (float)$price; $this->callMethod($id, $price); } |
echo ((true ? 'true' : false) ? 't' : 'f');
.&&
et ||
dans vos conditions : echo ('X' == 0 && 'X' == true)
.Évitez d'utiliser des paramètres avec référence, comme ceci :
function is_ref_to(&$a, &$b) { ... } |
Les noms de table doivent commencer avec le préfixe de PrestaShop, à l'aide de "_DB_PREFIX_
" :
... FROM `'. _DB_PREFIX_.'customer` ... |
ps_cart
".ps_order
"._lang
" : "ps_product_lang
".Les mots-clés doivent être écrits en majuscule :
SELECT `firstname` FROM `'._DB_PREFIX_.'customer` |
Le caractère accent grave ("`
") doit encadrer les noms des champs SQL et des tables SQL :
SELECT p.`foo`, c.`bar` FROM `'._DB_PREFIX_.'product` p, `'._DB_PREFIX_.'customer` c |
Les alias de table doivent être nommés en prenant la première lettre de chaque mot, le tout en minuscule :
SELECT p.`id_product`, pl.`name` FROM `'._DB_PREFIX_.'product` p NATURAL JOIN `'._DB_PREFIX_.'product_lang` pl |
Lorsque d'un conflit survient entre deux alias de tables, le second caractère doit également être ajouté dans le nom :
SELECT ca.`id_product`, cu.`firstname` FROM `'._DB_PREFIX_.'cart` ca, `'._DB_PREFIX_.'customer` cu |
L'indentation doit être faite pour chaque clause :
$query = 'SELECT pl.`name` FROM `'._DB_PREFIX_.'product_lang` pl WHERE pl.`id_product` = 17'; |
JOIN
dans une clause WHERE
.Voici un bref tutoriel pour installer la moulinette de norme sur son PC et l'utiliser pour valider ses fichiers. La moulinette de norme passe par PHP CodeSniffer qui est un package de PEAR (http://pear.php.net/package/PHP_CodeSniffer/). La norme PrestasShop a été créée pour l'occasion, constituée de nombreuses règles reprises des normes déjà existants, plus un certain nombre de règles personnalisées pour coller davantage au projet.
La norme PrestaShop est disponible via SVN ici : http://dev.prestashop.com/svn/v1/branches/norm (cette étape est obligatoire pour la suite).
Pour correctement installer la norme, il faut a tout prix la renommer en "Prestashop" (et non pas "norm"). |
Suivez ces étapes si vous utilisez PhpStorm (http://www.jetbrains.com/phpstorm/) :
phpcs
;/Standards
de CodeSniffer).Plusieurs plugins existent sur le net. Par exemple, vous pouvez utiliser celui-ci : https://github.com/bpearson/vim-phpcs/blob/master/plugin/phpcs.vim
Placez-le dans votre dossier ~/.vim/plugin
.
Vous pouvez rajouter deux raccourcis (par exemple, F9 pour tout afficher et Ctrl+F9 pour masquer les warnings) dans votre fichier .vimrc
en mode normal et insertion:
nmap <C-F9>:CodeSniffErrorOnly<CR> imap <C-F9> <Esc>:CodeSniffErrorOnly<CR> nmap <F9> :CodeSniff<CR> imap <F9> <Esc>:CodeSniff<CR>a |
Vous n'êtes pas obligé d'utiliser PhpStorm ou Eclipse pour profiter de la norme. Vous pouvez également installer PHP CodeSniffer afin de l'appeler en ligne de commande :
$> apt-get install php-pear
$> pear install PHP_CodeSniffer
/Standards
de CodeSniffer$> svn co
http://svn.prestashop.com/branches/norm/
/usr/share/php/PHP/CodeSniffer/Standards/Prestashop
$> phpcs --config-set default_standard Prestashop
Les différentes options de la commande sont disponibles et bien expliquées dans la doc, voici cependant une façon simple de le lancer :
$> phpcs --standard=/chemin/vers/norme/Prestashop /folder/or/fileToCheck |
Afin de n'afficher que les erreurs et non pas les warnings :
$> phpcs --standard=/chemin/vers/norme/Prestashop --warning-severity=99 /chemin/ou/fichierAVerifier |
Si vous avez installé PHP CodeSniffer "à la main", l'exécutable se trouve dans le dossier /scripts
de PEAR.
Pour les utilisateurs Windows, un fichier
|