Coding Standard

Un article de PhpMyVisites documentation.

Jump to: navigation, search

Sommaire

Coding Standard

Pourquoi adopter un style commun ?

Extrait de http://www-portal-stage.oracle.com/technology/tech/opensource/PHP_Coding_Standard.htm

Good Points
When a project tries to adhere to common standards a few good things happen:
   * programmers can go into any code and figure out what's going on
   * new people can get up to speed quickly
   * people new to PHP are spared the need to develop a personal style and defend it to the death
   * people new to PHP are spared making the same mistakes over and over again
   * people make fewer mistakes in consistent environments
   * programmers have a common enemy :-) 
Bad Points
Now the bad:
   * the standard is usually stupid because it was made by someone who doesn't understand PHP
   * the standard is usually stupid because it's not what I do
   * standards reduce creativity
   * standards are unnecessary as long as people are consistent
   * standards enforce too much structure
   * people ignore standards anyway 

Pourquoi phpMyVisites n'impose pas un coding style 'standard' ?

Nous pensons que les coding guidelines sont trop parfois trop restrictives, et parfois incomplètes. Nous préférons donc faire un résumé de ce qui nous semble indispensable et important. Nous avons pour cela utilisé plusieurs guides différents (5 au total) et fait un résumé bilan des meilleures idées et concepts, pour présenter l'ensemble des règles suivantes. Les points non soulignés sont donc laissées à la liberté d'expression du développeur !

Introduction

Quelques notions introductives :

  • noms de fonctions, noms de variables, noms de classes et de méthodes, en anglais
  • fonctions documentées en anglais selon la norme javadoc, la documentation est générée par phpDocumentor
  • les commentaires au sein des fonctions sont à écrire en priorité en anglais. Si vraiment vous ne pouvez ou ne voulez pas, le français est autorisé. L'anglais reste très largement conseillé
  • les fichiers code source sont tous encodés en UTF-8. Cela permettra à tous les développeurs d'avoir exactement le même rendu final, quel que soit leur pays et leur langue. Ce sera notamment utile pour les noms des développeurs étrangers.
  • la programmation objet est obligatoire et de toutes façons imposée par l'architecture de phpMyVisites

Général

Commentaires généraux sur le style de codage à utiliser obligatoirement

  • largeur maximum des lignes : 100 caractères (et non 80)
  • utiliser des tabulations et non des espaces. Chacun règle la taille de ses tabulations (4 semble être un bon chiffre). Ne pas transformer automatiquement ses tabulations en espace comme le proposent certains logiciels !
  • pour les if then else les 2 écritures classiques sont tolérées
if (condition)
{
   ...
}
else
{
   ...
}

et

if (condition) {
    ...
} else if (condition) {
    ...
} else {
    ...
}

La première semble plus claire et est conseillée ! Moi je conseille la deuxième, beaucoup plus simple à lire et plus concise :-P !

  • faire une bonne utilisation des espaces pour les blocs d'égalité
$a        = 'hello';
$bbbb     = 'world';
$cccccccc = 'foobar';
  • en cas de multiples tests bien mettre en avant sur des nouvelles lignes plus indentées les tests logiques
if ((condition1 && condition2)
         || (condition3 && condition4)
         ||!(condition5 && condition6)) 
{
    doSomethingAboutIt();
}
  • ne pas mettre plus d'une action par ligne (statement).
$i_toto = 1;
$i_tata = 2;
  • utiliser <?php et non <? en début de fichier (et veillez à ne pas laisser de ligne vide au début ou à la fin des fichiers
  • mettre les mots clés SQL en majuscule
SELECT   S.first_name, S.last_name 
FROM     students S
WHERE    S.email =  
ORDER BY S.last_name";
  • mettre les index des tableaux entre guillemets simples
Examples :
   $foo = $assoc_array[blah]; IS WRONG
   $foo = $assoc_array['blah']; IS OK

Commentaires

  • pour les commentaires en une ligne utilisez le style
// ici le commentaire
  • pour les commentaires sur plusieurs lignes utilisez le style
/* ici
 * un 
 * commentaire
 */
  • commentaires de fonctions, classes, méthodes respectent la norme javadoc
  /**
  * what the function does in one line.
  * more detailed description on 0-n lines, if needed.
  * @access  [public|static|pseudostatic]
  * @param   [string|int|double|bool|array|object|mixed] $paramName1 desc
  * @param   [string|int|double|bool|array|object|mixed] $paramName2 desc
  *  ...
  * @param   [string|int|double|bool|array|object|mixed] $paramNameN desc
  * @return  datatype  description
  * @throws  not until PHP 5
  * @see     some_function()
  * @todo    description
  * @since   ATutor version, PHP version   (comma separated list)
  * @status  stable|experimental           (if not set then considered stable)
  * @pattern singleton|factory|mvc|observer|facade|...
  * @author  description                   (comma separated list)
  */
  function something() 
  {
      ...
  }

Conventions de nommage

Cette partie est très importante et doit être scupuleusement suivie !

  • variables : utiliser le style "studly caps". Chaque premier caractère d'un nouveau "mot" doit être une majuscule, sauf le tout premier.
Examples :
 $currentuser is WRONG
 $current_user is WRONG
 $currentUser is OK
 $isLogged
 $setParamsOn
  • fonctions : utiliser le même style que les variables. De préférence sous forme de verbes (les fonctions effectuent, il existe forcément un verbe pour cet effet... !).
Examples :
 getToto()
 loadFoo()
 sellMs()
 phpmvRocks()
 cocoricoDeBonMatin()
Examples :
 L'utilisateur est il loggué ?
 isUserLogged()
 phpMyVisites est il puissant ?
 isPhpmvPowerfull() 
Note : ne pas utiliser la notation pdf2html mais plutôt pdfToHtml pour plus de clarté (confusion possible entre pdf2Html sinon...)
  • classes : elles suivent également le style StudlyCaps, mais avec une majuscule au début
class DatabaseLayer
class BrowserDetection
  • utilisez à bon escient les préfixes ou suffixes 'naturels' comme *Count, temp*, etc.
  • ne pas utiliser des noms de variables à 1 caractère seulement, excepté des index dans les boucles ($i, $j, $k, etc.)
  • pour combler le manque de précision de php sur le type des variables, il est parfois très bien vu de typer les array, string, integer, bool avec un préfixe
a_ : tableau (array)
s_ : chaîne (string)
i_ : entier (integer)
b_ : booleen (boolean)
  • également pour les variables globales
g_ : globale (global)
  • écrire true, false, et null en minuscule

Programmation

  • ne pas utiliser les variables globales sauf s'il n'y a pas d'autre solution, et dans ce cas se concerter entre développeurs auparavant.
  • il faut initialiser les variables
$a_t = array();
$s_t = '';
  • connaître et savoir utiliser === et !==
  • dans le switch, quand on fait un 'return' ne pas oublier le 'break'
switch ($x) {
     case 'hello':
     return TRUE;
     break;
}
  • utiliser des 'foreach' plutôt que des 'while(list($t,) = each($t2))'
  • pas de magic numbers, ces nombres qui apparaissent dans le code sans justification particulière, comme par magie. Définir des constantes ou variables ayant comme valeurs ces magic number, mais ne pas faire les tests directement !
  • optimiser les boucles for et autres, notamment lors de l'utilisation des sizeof()
Example :
 // le sizeof() est appelé à chaque itération de la boucle : MAUVAIS !
 for ($i = 0; $i < sizeof($post_data); $i++)
 {
     doSomething();
 }
 
 // le sizeof() est calculé une fois au départ, seulement : BON !
 for ($i = 0, $size = sizeof($post_data); $i < $size; $i++)
 {
     doSomething();
 }
  • utilisez plutôt sizeof() que count()
  • utilisez plutôt strpos() que strstr()
  • ne pas utiliser la possibilité de Smarty de mettre du code PHP dans les templates via les tags . C'est dangereux et l'on peut faire sans !
  • quand une fonction doit retourner un bool, retournez un bool soit true soit false et non pas 1 ou 0

IMPORTANT fonctions propres à phpMyVisites

  • pour récupérer une variables utiliser la fonctions getRequestVar() qui sécurise les données
  • pour stripslasher utiliser la fonction stripslashesPmv() qui prend en compte les magic_quote
  • pour faire des requêtes utiliser query() au lieu de mysql_query()

XHTML/CSS

  • Faire du code xhtml et css valide, c'est à dire respecter les standards
  • Bien respecter le séparation de la structure des données de la présentation des données.
    • La structure, c'est le (x)html. Il ne doit pas contenir de balise de présentation.
      • Pas de balise FONT
      • Pas de balise CENTER
      • pas de balise B, utiliser STRONG qui sera définit dans la feuille de style
      • pas de balise I
      • Pas de balise U
      • Pas de balise BR, la feuillede style se charge de la présentation
      • Les tables ça sert à faire des tableaux, pas de la présentation
      • Il y a des balise si on a besoin de faire des listes
      • Il y a des balise si on a besoin de faire des titres (H1, H2...)
      • Les balises span doivent être utilisées à bonne escient, pas pour remplacer les balises interdites de type U ou I.
    • Ce n'est pas parce que le code passe au validateur du w3c qu'il est correct. C'est comme en français, il y a l'orthographe et la grammaire. Le validateur ne s'occupe que de l'orthographe. Ce qui n'empèche qu'il faut le passé et ne pas avoir d'erreur.
    • La présentation, est géré par les css. Dans les CSS sont défini les comportement des balises, des class et des id.
      • Ne pas employer de class lorsque cela n'est pas nécessaire, un titre doit utiliser une balise H et non un span avec une class="titre" par exemple
      • Bien vérifier qu'on ne peut aps utiliser un style déjà existant avant d'en définir un nouveau
  • Outils conseillés pour le développement