L'adoption d'un standard de codage commun permet aux développeurs de mieux communiquer ensemble, de favoriser la relecture et diminuer le nombre de bugs "idiots". Je préconise un standard très proche de celui utilisé par SUN dans la conception Java, et de celui du framework PEAR ce qui offre l'avantage de s'appuyer sur une "norme" plus ou moins "industrielle".

Table des matières

  1. Conventions de nom
    1. Noms adaptés
    2. Classes
    3. Fonctions et Méthodes
    4. Variables
    5. Constantes
  2. Indentation
  3. Longueur de lignes
  4. Structures de contrôles
  5. Appels de fonction
  6. Commentaires
    1. phpDocumentor
    2. Sources et fichiers
  7. Programmation objet
    1. Gestion
    2. Encapsulation
    3. Ordres de déclaration
  8. Include et Require

1. Conventions de nom

1.1 Noms adaptés

Le nommage des différents éléments est crucial pour la compréhension du code. Un nom est le résultat d'un long processus de pensée résultant du sujet étudié. Si les noms sont appropriés alors tout les éléments s'adaptent ensembles naturellement, les programmeurs peuvent donc comprendre les rapports et leurs significations.

1.2 Classes

Les classes doivent avoir un "nom parlant".
Eviter les abréviations lorsque cela est possible.
Les noms de classes doivent toujours commencer par une majuscule.
L'architecture hiérarchique des classes se prononce en utilisant le style "studly caps" (aussi connus sous les noms de "bumpy case" ou "camel caps"),
donc chaque niveau de la hiérarchie est interprété par le début d'une nouvelle majuscule.
En d'autre terme employez les lettres majuscules comme séparateurs de mot, minuscules pour le reste d'un mot.
Chaque classe est un fichier, le nom du fichier commence toujours par "C_" suivi du nom de la classe avec la première lettre en minuscule.

Exemple :

<?php
        
        class MyClass {
                [...]
        }

?>
Cette classe sera enregistrée dans le fichier "C_myClass.php".

1.3 Fonctions et Méthodes

Habituellement chaque méthode et fonction effectue une action, ainsi le nom doit être explicite afin de savoir a partir du nom ce qu'il fait. Les fonctions et les méthodes doivent être nommées en utilisant le style "studly caps" à la seule différence que le premier caractère du nom de la fonction doit être une minuscule. La déclaration des méthodes et fontions respecte l'indentation classique des parenthèses.

Note : les arguments possèdant des valeurs par défaut vont à la fin de la liste des arguments.

Exemple :

<?php
        
        myFunction (&$foo, $bar = false) {
                [...]
        }
        
        getElement($param) {
                [...]
        }

?>

Les fonctions privées d'une classe sont précédés d'un simple souligné (_).

Exemple :

<?php
        
        _myFunction {
                [...]
        }

?>

1.4 Variables

Les variables doivent être écrites en minuscule et doivent être systématiquement déclarées avant leur utilisation.
De plus elle doivent être obligatoirement préfixées par une lettre (en majuscule) définissant leur type.

Exemple :

<?php

        // tableau
        $aFoo = array();       
        
        // objet
        $aFoo = new Object();
        
        // chaîne
        $sFoo = 'string';
        
        // booléen
        $bFoo = true
        
        // entier
        $iFoo = 1;

?>

1.5 Constantes

Les constantes doivent être écrites en majuscule, chaque mot doit être séparé d'un simple souligné (_).

Exemple :

<?php

        define("HELLO_WORLD", "Hello world!");

?>

2. Indentation

L'indentation doit être de 4 espaces (ou 1 tabulation). Il n'y a aucune règle arbitraire quant au niveau d'indentation maximum par contre si le niveau d'indentation est plus de 4 ou 5, il est préférable de factoriser votre code si cela est possible.

Exemple :

<?php

        myFunction($foo, $bar, &$quux = array()) {
                if ($foo > 0) {
                        [...]
                        foreach($bar as $val) {
                                [...]
                        }
                }
                [...]
        }

?>

3. Longueur de lignes

Une ligne ne doit pas dépasser 80 caractères.

4. Structures de contrôles

Les instructions de contrôle doivent avoir un espace entre le mot clé de l'instruction et la parenthèse ouvrante, afin de ne pas les confondre avec des appels de fonction. Il faut toujours utiliser des parenthèses, même dans les situations où elles sont techniquement optionnelles. Leur présence augmente la lisibilité du code et réduit le risque d'erreur logique lors de l'ajout de nouvelles lignes de code.

Exemple :

<?php 

        if ((6 == $foo) || (true == $bar)) {
                [...]
        } elseif (($foo > 10) && ($bae > 2)) { 
                [...]
        } else { 
                [...]
        }

?>

La constante doit être toujours du côté gauche de l'expression d'une égalité.

Exemple :

<?php

        if (6 == $foo) {
                [...]
        }

?>

5. Appels de fonction

Les fonctions doivent être appelées sans espace entre le nom de la fonction, la parenthèse ouvrante, et le premier paramètre; avec un espace entre la virgule et chaque paramètre; et aucun espace entre le dernier paramètre, la parenthèse fermante et le point virgule. Dans le cas d'un bloc d'instructions similaire, des espaces supplémentaires peuvent être ajoutés pour améliorer la lisibilité.

Exemple :

<?php

  $nux   = foo($bar, $baz, $quux);
  $beaq  = foo($foo, $bae, $qux);

?>

6. Commentaires

6.1 phpDocumentor

phpDocumentor est un outil qui permet de générer automatiquement la documentation technique d'une application écrite en PHP (inspiré de JavaDoc).
Pour cela, le programmeur doit agrémenter son code source de quelques commentaires particuliers décrivant les principaux éléments du programme.
La documentation générée se présente sous la forme d'un ensemble de pages HTML (ou autres formats de sortie, PDF, CHM ...). Il existe une grande quantité d'options et de marqueurs qui permettent d'enrichir la documentation avec des informations particulières.
Le résultat obtenu est semblable à la documentation officielle des classes PEAR consultable sur Internet. Tout programmeur PHPse familiarise donc immédiatement avec la documentation générée par phpDocumentor (http://manual.phpdoc.org/HTMLframesConverter/earthli/).

6.2 Sources et fichiers

La documentation du code source doit suivre la convention phpDocumentor. Il se présente sous la forme d'un commentaire multilignes qui débute par le jeu de caractères slash suivit par deux étoiles " /** ". Chaque ligne suivante commence par une étoile, et le commentaire se termine par une étoile suivi d'un slash " */ ". Ce type de commentaire doit être ajouté avant chaque élément important du code. Les paramètres spéciaux sont assez nombreux mais quelques uns d'entre eux sont cependant fréquemment utilisés. Les paramètres sont séparés de la description par une ligne vide, ils débutent par un arobase, suivit du nom du paramètre, puis du commentaire correspondant.

Voici les paramètres les plus utilisés et leurs fonctions :

  • @author : auteur de la classe, de la méthode ou de la fonction
  • @version : version de la classe, de la méthode ou de la fonction
  • @param : permet de commenter le paramètre
  • @see : permet de faire référence à d'autres classes, méthodes ou fonctions
  • @since : permet de spécifier la compatibilité.
  • @return : même fonctionnement que param, mais pour décrire ce que renvoie la fonction ou la méthode

Exemple :

<?php

        /**
        * Description de ma fonction
        *
        * @author: Nicolas SUPRIN <xxxx@domain.com>

        * @version: 1.1.1.0
        * @param: $foo  la description de foo
        * @param: $bar  la description de bar
        * @see: GetElement
        * @since: 1.1.1.0
        * @return description de la valeur de retour de la fonction
        */
        myFunction($foo, $bar) {
                if ($foo > 0) {
                        [...]
                        foreach($bar as $var) {
                                [...]
                        }
                }
                [...]
        } 


?>

7. Programmation objet

7.1 Gestion

Pour une meilleure gestion des classes, il faut créer un fichier pour chaque classe, cela permet de maintenir plus facilement les sources. Pour le nommage des fichiers voir le paragraphe 1.2.

7.2 Encapsulation

L'encapsulation des données est un des concepts essentiels de la programmation objet. Concrètement cela revient à "cacher" les données aux programmes qui les utilisent et à fournir à ces programmes des méthodes d'accès à ces données.

Cette démarche vise à atteindre deux objectifs :

  • Augmenter la sécurité des programmes
  • Faciliter la maintenance de l'objet

L'encapsulation masque les données aux programmes utilisateurs. Elle offre à ces programmes utilisateurs des fonctionnalités (méthodes) qui sont comme des interfaces entre les données de l'objet et le programme utilisateur. Ainsi, on pourra modifier de manière complètement transparente, l'implémentation de ces méthodes, sans que le programme utilisateur ait besoin de modifier son code. Il suffit que les méthodes conservent les mêmes prototypes.

Cela consiste donc à créer des méthodes permettant de récupérer les données, on appelle ces méthodes des accesseurs.

Exemple :

<?php

class MyClass {
	
	var $S_foo = '';
	
	function setFoo($value) {
		$this->S_foo = $value;
	}
	
	function getFoo() {
		return $this->$S_foo;
	}
}


 /**
  * Exemple d'utilisation
  */

  $foo = new MyClass();
  $foo->setFoo('variable');
  echo $foo->getFoo();
  
?>

7.3 Ordres de déclaration

L'ordre des déclarations des attributs et des fonctions privés ou publics d'une classe doit être dans cette organisation :

  1. Attributs privés
  2. Attributs publics
  3. Constructeur
  4. Destructeur
  5. Fonctions privées
  6. Fonctions publiques

Exemple :

<?php

  class MyClass {

    // Private
    var $_S_foo = '';

    // Public
    var $I_bar;

    // Constructeur
    public function __construct() {
        $this->I_bar = 0;
    }
   
    // Private
    function _workFoo() {
        [...] 
    }

    // Public
    function setFoo($value) {
        $this->_S_foo = $value;
    }

    function getFoo() {
        return $this->$_S_foo;
    }

}

?>

8. Include et Require

A chaque endroit où vous voulez inclure de façon inconditionnelle un fichier, utilisez require_once(). A chaque endroit où vous voulez inclure de façon conditionnelle un fichier, utilisez include_once(). Ces deux méthodes assurent que le fichier n'est inclu qu'une seule fois. Elles partagent la même liste de fichiers, il donc possible de les mélanger - un fichier inclu avec require_once() ne sera pas inclu une seconde fois par include_once().

Dans les versions antérieures à PHP 4, ces fonctions n'existe pas, seules les fonctions require et include existaient. Toutefois il existe une parade pour remédier à cette problèmatique via une constante globale.

Exemple

<?php

    if (!defined("MY_CLASS")) {
        define("MY_CLASS", 1 );
        include("/lib/C_myClass.php");
    }

?>