Conventions
Un article de FreeGlobes Wiki.
Le code de FreeGlobes a été écrit dans le respect de règles de codages, très proches des règles de codage définies pour le langage Java. en respectant ces règles, vous faciliterez la relecture et la maintenance de votre code.
Configuration PHP
FreeGlobes nécessite que certaines variables PHP aient une valeur bien définie. Ces obligations sont dans le but d'assurer que le script fonctionne de manière sécurisée.
- allow_call_time_pass_reference : OFF
- register_globals : OFF
- error_reporting : E_ALL
- magic_quotes_gpc : OFF
Balises PHP ouvrantes et fermantes
Les blocs d'instructions PHP doivent obligatoirement être déclarés en utilisant la balise ouvrante <?php et la balise fermante ?>.
La version abrégée <? ?> est à proscrire.
Exemple de code :
<?php echo 'hello world'; ?>
// A eviter <?php echo 'hello world'; ?>
D'autre part, on évitera d'écrire des instructions PHP sur la même ligne que les balises ouvrantes et fermantes.
On évitera également ce genre de code maladroit :
// Maladroit <?php echo 'hello'; ?> <?php echo 'ok'; ?>
Ce genre de code apparait souvent après un rajout rapide de code PHP. Lorsque plusieurs instructions PHP se suivent de cette manière, on remplacera le code ci-dessus par le code suivant :
<?php echo 'hello'; echo 'ok'; ?>
A noter que dans cet exemple, on pourra également rassembler les "echo" mais ce n'est pas l'objet de cet exemple de mettre cela en évidence.
Inclusion d'un fichier
Lorsque vous souhaitez inclure un fichier, vous devez le faire par chemin absolu. Pour cela, vous disposez de la constante SCRIPT_ROOT_PATH.
Exemple d'inclusion de fichier :
require_once (SCRIPT_ROOT_PATH.'/include/common.php');
SCRIPT_ROOT_PATH contient le chemin absolu vers le script sans '/' à la fin. Utilisez systématiquement "require_once" pour inclure vos fichiers afin qu'ils ne soient inclus qu'une seule fois et afin d'éviter des erreurs malencontreuses.
Note : SCRIPT_ROOT_PATH est disponible en incluant par chemin relatif le fichier init.php. Ce dernier initialise cette constante. init.php est inclus par défaut dans le script donc cette constante est accessible dans tout le script.
Note : Dans le cas de la partie administration d'un plugin (vous êtes en train d'écrire l'administration du plugin), vous disposez de la constante PLUGIN_ROOT_PATH qui est le chemin absolu jusqu'à la racine de votre plugin, sans / à la fin.
Exemple : vous êtes dans le plugin info dans le fichier index.php. Vous souhaitez inclure le fichier file.php qui se trouve dans le répertoire include/ de votre plugin. Vous devrez faire :
<?php require_once (PLUGIN_ROOT_PATH.'/include/file.php'); ?>
Structures de contrôle
Les structures de contrôle sont les instructions if, switch, for, while, foreach, etc. Il n'est pas obligatoire de laisser un espace entre le mot clef de l'instruction et la condition.
Exemple de code :
<?php
if (condition1 && condition2) {
...
}
foreach ($tableau as $k => $v)
{
...
}
?>
La position des accolades peut être faites des deux manières ci-dessus. On préfèrera tout de même la 2ème solution proposée ci-dessus.
Appels de fonctions
Les fonctions sont appelées sans aucun espace entre le nom de la fonction, les parenthèses et les paramètres. Par exemple :
<?php maFonction($var1,$var2); ?>
Si la fonction est retournée dans une variable, on mettra au moins un espace de part et d'autre du signe égal. Par exemple :
<?php $var = maFonction($var1); ?>
Opérations sur les variables
L'espace entre le nom de la fonction et ses arguments est toléré. En revanche, l'assignation d'un variable doit obligatoirement se faire avec un espace de part et d'autre du signe.
<?php // Correct $var = $a + $b; // Incorrect $var=$a+$b; // Incorrect $var = $a+$b; ?>
Tous les opérateur d'une opération entre variables doivent être écrit avec un espace de part et d'autre. Il s'agit d'une mesure visant à faciliter la relecture du code.
Guillemets simples et doubles
On utilisera les guillemets simple (') en priorité aux guillemets doubles (""). L'utilisation des guillemets doubles ne devra se faire qu'en cas d'absolue nécessitée.
Exemple de code :
<?php // Ici des simples guillemets suffisent echo 'salut tout le monde'; // Ici des guillemets doublent conviendront mieux : on évite d'avoir à échapper le ' echo "salut l'expert !"; ?>
Concaténations
Les concaténations doivent être faites en utilisant le délimiteur ".". Les autres délimiteurs ne sont pas tolérés même s'ils fonctionnent de la même façon. D'autre part, lorsque vous concaténez une chaine avec une variable, faites le de manière explicite. Voici un exemple pour éclaircir tout ça :
<?php // correct $a = 'hello '.$b; // fonctionne mais incorrect $a = "hello $b"; ?>
La 2ème solution fonctionne aussi bien que la 1ère mais on l'évitera. La 2ème solution est nettement plus lisible car elle profite de la colorisation syntaxique dans un editeur comme NotePad++.
Définitions des fonctions
Les accolades de la fonctions sont placées sous le nom de celle-ci et le code est indenté d'un niveau. Par exemple :
<?php
maFonction($var1,$var2 = 0)
{
return $var1 + $var2;
}
?>
On respectera la même règle que pour l'assignation concernant les valeurs par défaut des variables déclarées dans le prototype de la fonction.
Commentaires
Les commentaires du code doivent obligatoirement être rédigés en anglais. Il existe plusieurs patrons de commentaires possibles, chacun ayant pour tâche de décrire un élément précis du code.
Voici un commentaire simple, à insérer pour expliquer une ligne précise du code :
// la ligne ci-dessous fait ... $var = ($a * $b) / 2;
Voici le commentaire type pour décrire une fonction/méthode :
/*
* Displays the links on main display
* @function myFunc
* @param type name : name of the ...
* @param type name : name of the ...
* @return string : what it returns...
*/
function myFunc()
{
...
}
La première ligne est une explication brève de ce que fait la fonction/méthode. @param designe un paramètre de la fonction. Cette balise est suivie du type du paramètre, de son nom puis " : " et une explication brève de son utilité si jamais le nom de la variable n'est pas suffisamment explicite.
Voici un commentaire pour décrire une classe :
/* * Object Manager * @class MyObjectManager * @package Kernel * @author Jerome Loisel */
La première ligne est un bref explicatif de ce que fait la classe, son utilité.
@class : nom de la classe
@package : nom du package auquel est rattachée la classe
@author : auteur de la classe
Si vous devez rédiger un commentaire long en entête de fichier ou pour décrire tout un bloc d'instructions, utilisez la structure de commentaires suivante :
/* * * blabla * */
Conventions de nommage
Classes
Les classes sont toujours nommées avec des lettres non accentuées, mots collés les uns aux autres et chaque mot commence par une majuscule.
Exemple :
MyObject
Les noms de classes sont à mettre en anglais en priorité.
Fonctions
Les fonctions sont toujours nommées avec des lettres non accentuées, mots collés les uns aux autres et chaque mot commence par une majuscule excepté le premier mot.
Exemple :
myFunction
Les noms des fonctions sont également à mettre en anglais.
Variables
Les variables sont toujours nommées avec des lettres non accentuées, les mots sont tous en minuscules et sont séparés par des _.
Exemple :
<?php $my_var = 'text...'; ?>
Les noms des variables doivent avoir un sens.
Constantes
Les constantes doivent obligatoirement être en majuscules, sans accents ni caractères speciaux. Chaque mot doit être séparé par un _ et le nom de la constante doit avoir un sens (il doit être évoquateur).
Exemple :
<?php
define('SCRIPT_ROOT_PATH',dirname(__FILE__);
?>
Indentation
Utilisez une indentation avec des tabulations vraies : n'utilisez pas l'espace pour indenter le code ! La largeur pratique d'une indentation par tabulation est de 5 espaces dans le code de FreeGlobes.
Variables reçues par formulaire
Contrôlez systématiquement les variables reçues par formulaire de la manière suivante :
<?php // Variable 'ma_variable' reçue en GET par formulaire $ma_variable = isset($_GET['ma_variable']) ? $_GET['ma_variable'] : ""; ?>
Cette instruction est une contraction élégante de l'instruction suivante :
<?php
$ma_variable = ;
if (isset($_GET['ma_variable']))
{
$ma_variable = $_GET['ma_variable'];
}
?>
De cette manière vous diminuez la quantité de lignes de codes en contractant les blocs conditionnels uniquement dédiés aux tests de variables de formulaire. De plus, il est absolument nécessaire de tester les variables issues des formulaires pour des raisons de sécurité et de fiabilité du code.
Requêtes base de données
Que ce soit dans le code d'un plugin ou ailleurs dans la logique métier du script, il ne faut en aucun cas écrire explicitement les requêtes base de données.
Exemple incorrect :
<?php
// Le code est incomplet, mais c'est pour indiquer l'esprit d'un accès incorrect
$links = mysql_query("SELECT * FROM `links` WHERE `id`=1 LIMIT 10");
?>
Exemple correct :
<?php
$link_manager =& get_manager('link');
$criteria = new Criteria('id',1,'=');
$criteria->setLimit(1);
$links =& $link_manager->getObjects($criteria);
?>
Pour en savoir plus sur la gestion Orientée-Objet des accès base de données, référez-vous à la section correspondante du Wiki. De manière générale, aucune requête base de données ne doit être écrite de manière explicite dans votre code. C'est le noyau Objet de FreeGlobes qui se charge de le faire pour vous en fonction de critères que vous lui préciserez.
