Matomo/CodingStandard

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 Piwik 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 n'est pas obligatoire mais fortement encouragée Marco

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

Exemples :
   $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.

Exemples :
 $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... !).

Exemples :
 getToto()
 loadFoo()
 sellMs()
 phpmvRocks()
 cocoricoDeBonMatin()

Exemples :
 L'utilisateur est il loggué ?
 isUserLogged()
 Piwik 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 faut 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()

Exemple :
 // 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();
 }

de même que pour le if on peut écrire

 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 à Piwik

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()