Principes des Règles de Développement
Dans tout projet de développement, les codes source sont vus, revus et modifiés par un certain nombre de développeurs et.ou de testeurs.
Cela est particulièrement vrai dans les projets de développement de logiciels libres, où le nombre de développeurs participants va croissant avec la popularité du produit !
C'est pour ces raisons qu'il est nécessaire de mettre en place un certain nombre de règles de développement.
Ces règles définissent la manière dont le code doit être écrit.
Ainsi, le respect des règles garantit qu'un code sera facilement lisible et maintenable par des développeur venant de tous horizons.
Les règles présentées ici seront volontairement simplifiées et limitées à l'essentiel, afin de permettre à chacun d'entrer rapidement dans le code, sans submerger les nouveaux développeurs de règles complexes.
Par ailleurs, le projet étant assez ancien, toutes les pages de code ne respectent pas encore totalement les règles indiquées ci-dessous. Cette situation s'améliore progressivement avec la réécriture systématique des pages.
Règles de Développement de Toutateam
Les règles de développement de Toutateam s'échelonnent sur plusieurs niveaux :
- Règles de codage : comment chaque page de code devra être écrit
- Règles d'organisation : comment devra se faire chaque nouvelle contribution, l'ajout de nouveaux modules, de nouvelles classes
- Procédures simplifiées : les schémas à appliquer pour réaliser certaines tâches spécifiques, tel que l'ajout d'un addon, ou d'un module d'administration
Règles de codage
Nommage des variables
- Les noms des variables doivent être explicites
- Ils doivent être composés de un ou plusieurs mots dont la première lettre est en majuscules
- Toute variable doit être initialisée avant d'être utilisée comme paramètre d'une fonction.
- Exception aux deux règles précédentes : les variables utilisées pour les boucles
- Chaque variable doit être précédée d'un préfixe indiquant sa portée :
- $my : indique une variable locale à un module/fichier
- $the : paramètre d'une fonction
- $The : variable globale (comprendre : variable dont la portée et l'importance peut être considérée comme globale)
Exemple :
function add($theA,$theB)
{
$mySomme=$theA+$theB;
return $mySomme;
}
Nommage des fonctions et classes
- Le nom des fonctions doit être explicite : le nom de la fonction DOIT exprimer son but et l'information retournée
- Dans tous les cas, hors préfixe le nom de la fonction doit être composée de mots entiers commençant par une majuscule
- Le préfixe de la fonction définit ce qu'elle va retourner :
- Préfixe "is" : la fonction retourne un booléen, fonctions utilisées pour vérifier un état d'une propriété
- Préfixe "get" : la fonction retourne un contenu ou une valeur.
En règle générale, retourner FALSE en cas de problème, et tester le retourn avec la triple égalité : ===
- Préfixe "show" : la fonction affiche du contenu directement sur le navigateur, et retourne un booléen
- Préfixe "check" : la fonction retourne un boolée, fonctions utilisées pour réaliser un ou plusieurs tests
- En dehors des cas précédents, aucun préfixe n'est requis.
- Les classes spécifiques doivent commencer par le préfixe "cls"
Exemple :
function isFieldVisible($theFieldName)
Nommage des variables de formulaire
- Les variables de formulaire doivent être explicites : elles doivent être constituées de mots commençant par une majuscule
- Un préfixe doit être ajouté au début de chaque variable de formulaire :
- Champ texte : txt
- Champ textarea : txt
- Champ caché : hid
- Champ checkbox : chk
- Liste déroulante : cmb
- Liste de choix : lst
- Formulaire : form
- Chaque champ de formulaire doit être identifié par un nom unique et un id unique aussi, identique au nom, sauf cas spécifique
Structure du code
- Règle unique pour tout le code : Une ligne, Une fonction
- Exception à la règle : l'usage de la macro (bool)?true:false;
- Les tabulations doivent être fixées à 4 espaces
- L'accolade qui suit les fonctions et les boucles for/while/... doit être placée à la ligne
- A l'intérieure de toute accolade, le code est indenté d'une tabulation
- Les variables incluses dans un bloc de texte doivent être sorties de celui-ci : "mon bloc avec ma variable ".$myVar." au milieu"
Cette règle facilite visualisation des instances d'une variable sous Eclipse.
Exemple :
class clsTest
{
function clsTest($theParam)
{
for($i=0;$i<=5;$i++)
{
echo "Hello world : ".$i."\n";
}
}
}
Règles d'organisation
Placement des nouveaux fichiers
- Les fichiers relatifs à un module doivent être placés dans le répertoire de ce module (exemple : /calendar, /contacts, etc)
- Si le code source est susceptible d'être utilisé par plusieurs modules, il doit être déposé dans le répertoire /lib
- Avant tout ajout de module au répertoire /lib, le développeur doit vérifier qu'aucune fonction similaire n'existe déjà
- Si le code source mutualisé est un code javascript, le déposer dans /lib/js
- Les fichiers relatifs à un template (ou enveloppe) sont placés dans le répertoire de l'enveloppe correspondante
Nommage des fichiers
- Le nom d'un nouveau fichier contenant une classe doit être : nomfichier_class.php
- Le nom du fichier d'une nouvelle classe doit contenir le nom de la classe principale du fichier
- Un nouveau fichier relatif directement à un module doit porter comme préfixe le nom du module
Procédures simplifiées