Par Nicolas SUPRIN, vendredi 9 février 2007 à 09:52 | PHP | #84 | rss
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
- Conventions de nom
- Indentation
- Longueur de lignes
- Structures de contrôles
- Appels de fonction
- Commentaires
- Programmation objet
- 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
$A_foo = array();
// objet
$O_foo = new Object();
// chaîne
$S_foo = 'string';
// booléen
$B_foo = true
// entier
$I_foo = 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 :
- Attributs privés
- Attributs publics
- Constructeur
- Destructeur
- Fonctions privées
- 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");
}
?>
Aucun commentaire pour le moment.
Aucun trackback.
Pour faire un trackback sur ce billet : http://www.blog.cactuscrew.com/tb.php?id=84&chk=jr021v