Home » Publications » Conventions de codages en PHP

Conventions de codages en PHP

Version 1.0.2 - Working Draft - Fichiers brut : html
Régis GAIDOT <regis @ gaidot.net>

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.

L'utilisation de la langue de Shakespeare est obligatoire.

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.

Exemple :

<?php

  class MyClass {
    [...]
  }

?>

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". Chaque premier caractère d'un nouveau "mot" doit être une majuscule. La déclaration des méthodes et fonctions 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.

Exemple :

<?php

  $foo = array();
  $foo[0] = "Hello world!";

?>

1.5 Constantes

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

Exemple :

<?php

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

?>

2. Indentation

L'indentation doit être de 2 espaces, sans 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 (($foo == 6) || ($bar == true)) {
   [...]
 } elseif (($foo > 10) && ($bae > 2)) { 
   [...]
 } else { 
   [...]
 }

?>

La constante doit être toujours du côté droit de l'expression.

Exemple :

<?php

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

?>

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 JavaDoc

JavaDoc est un outil qui permet de générer automatiquement la documentation technique d'une application écrite en Java. 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. 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 java consultable sur Internet. Tout programmeur Java se familiarise donc immédiatement avec la documentation générée par JavaDoc (http://java.sun.com/j2se/javadoc/).

Il existe de multiples projets libre s'inspirant très fortement de l'outil permettant ainsi de réaliser ce type de documentation pour divers langage XSLTDoc, PHPDoc, DelphiDoc...

6.2 Sources et fichiers

La documentation du code source doit suivre la convention Javadoc. 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
@exception: permet de commenter les exceptions lancées par une méthode ou une fonction

Exemple :

<?php

  /**
   * Description de ma fonction
   *
   * @author: Régis GAIDOT <regis@gaidot.net>
   * @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 il est recommandé d'utiliser le nom de la classe en utilisant le style "studly caps" suivi de l'extention ".inc.php" et de sauvegarder ce dernier dans le répertoire "lib".

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.

Exemple :

<?php

  class MyClass {
  
   var $foo = "";
   
   function setFoo($aValues) {
    $foo = $aValues;
   }

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

  }


 /**
  * Exemple d'utilisation
  */

  $foo = new MyClass();
  // $foo->setFoo("MY_VALUE");
  $foo::setFoo("MY_VALUE");

  // echo $foo->getFoo();
  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 :

Attributs privés
Attributs publics
Fonctions privées
Fonctions publiques

Exemple :

<?php

  class MyClass {

    // Private
    var $foo = "";

    // Public
    var $bar = "";

   
    // Private
    function _workFoo() {
      [...] }

    // Public
    function setFoo($aValues) {
      $foo = $aValues;
    }

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

  }

?>

8. Arborescences et Fichiers

L'arborescence d'un projet est important, elle permet en effet de retrouver plus facilement les fichiers. Les fichiers doivent avoir des noms explicites. La liste ci-dessous montre le nom de chaque répertoire attendu pour un projet :

include : répertoire de module/bloc (morceaux de code).
lib : répertoire de librairie (classes, librairie de fonction...)
conf : répertoire de configuration (variables globales, constantes) du projet
images : répertoire des images du projet
template : répertoire de template (exemple : fichiers XSL)
doc : répertoire de documentation, on peux aussi retrouver le changelog
locale: répertoire des ressources strings (fichiers langue)

9. Code source

Afin que le code source soit plus lisible et maintenable, il est recommandé de décorréler les données traitées de l'affichage

Exemple

<?php

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

  $qux = new MyClass();
  $qux::setFoo("MY_VALUE");

 $foo = $qux::getFoo();
 $bar = $qux::GetBar();

?>

<?xml version="1.0" encoding="iso-8859-1"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="fr" lang="fr">
<head>
<title><?php echo $foo; ?></title>

<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
</head>
<body>
<p><?php echo $bar; ?></p>

<?php 

  include("/include/bae.php");  
?>

</body>
</html>

10. Resource strings

10.1 Introduction

Les "resource strings" existent principalement pour faciliter l'internationalisation des applications. Elle permet de faciliter la traduction des applications.

La plupart des applications communiquent avec l'utilisateur par des messages. Le stockage de ces messages s'effectue dans des variables spéciales et de manière uniforme dans des fichiers séparés.

10.2 Fichiers "resource strings"

Les fichiers "resource strings" doivent être situés dans le répertoire "locale". Le nommage du fichier "resource strings" est composé des deux lettres du pays suivi d'un simple souligné (_) et de deux autres lettres suivant la langue, voici la liste :

bg_BG : Bulgare
zh_CN : Chinois (Simplifié )
zh_TW : Chinois (Traditionnel)
cs_CS : Tchèque
de_DE : Allemand
en_GB : Anglais (Grande Bretagne)
en_US : Anglais (Etats unis)
es_ES : Espagnole
fr_FR : Français
el_GR : Grecque
it_IT : Italien
ja_JP : Japonais
ko_KR : Coréen
pl_PL : Polonais
pt_PT : Portugais
pt_BR : Portugais Brésilien
ro_RO : Roumains
ru_RU : Russe
sk_SK : Slovaque
uk_UA : Ukrénien

10.3 Variables

Les régles de nommage des variables doivent être appliquées. Toutes les chaînes doivent être préfixées de "rs".

Exemple :

<?php

  $rsfoo = "Hello world!";

?>

En ce qui concerne les variables composées d'une chaîne de caractères formatée, la fonction printf() est utilisée. Cette fonction attend une ou plusieurs directives. Les options de formatage de la fonction printf() sont les suivantes :

%b : nombre binaire
%c : caractère de code ASCII
%d : nombre décimal signé
%u : nombre décimal non signé
%f : nombre à virgule flottante
%o : nombre octal
%s : chaîne de caractères
%x : nombre hexadécimal

Exemple :

<?php

  /**
   * Fichier ressource string anglais
   *
   * @author: Régis GAIDOT <regis@gaidot.net>
   * @version: 1.1.1.0
   */

  $rsfoo = "Hello %s!";
  $rsbar = "Value of I:   %d";
  [...]
?>

<?php

  /**
   * [...]
   *
   * @author: Régis GAIDOT <regis@gaidot.net>

   * @version: 1.0.0.0
   */
   
  require_once("/locale/fr_FR");

  $rsbae = "World";
  printf(rsfoo, $rsbae); 


?>

11. 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/myclass.inc.php");
 }

?>

Toute reproduction ou représentation, intégrale ou partielle, par quelque procédé que ce soit du présent document, faite sans le consentement de l'auteur, est illicite et constitue une contrefaçon. Seules sont autorisées les copies prévues à l'article L.122-5 du Code de la Propriété Intellectuelle, ainsi que la redistribution, à titre gracieux uniquement, sur le lieu de travail du copiste d'une version imprimée de l'oeuvre, sous réserve que soient clairement mentionnés le nom de l'auteur et l'URL de la version officielle du document. Toute exploitation contre rétribution est explicitement interdite.

Régis Gaidot

Navigation

Conventions de codages en PHP

Table des matières

1. Conventions de nom

1.1 Noms adaptés

1.2 Classes

1.3 Fonctions et Méthodes

1.4 Variables

1.5 Constantes

2. Indentation

3. Longueur de lignes

4. Structures de contrôles

5. Appels de fonction

6. Commentaires

6.1 JavaDoc

6.2 Sources et fichiers

7. Programmation objet

7.1 Gestion

7.2 Encapsulation

7.3 Ordres de déclaration

8. Arborescences et Fichiers

9. Code source

10. Resource strings

10.1 Introduction

10.2 Fichiers "resource strings"

10.3 Variables

11. Include et Require

Shortcuts

Who ?

Blog