Convention de codage
Un article de LodelWiki.
Sommaire |
[modifier] Préambule
Ce document a pour but de définir un certain nombre de règles et de recommandations à suivre pour l'écriture du code de LODEL. Définir des conventions de codage présente de multiples avantages. le premier, évident, est la simplification des opérations de maintenance du code. Le code d'une application passe environ 80% de son temps en phase de maintenance. Respecter un certain nombre de conventions de nommage et de codage permet donc de gagner du temps lorsque on relit le code et que l'on corrige des bogues. Le second avantage est qu'elles permettent d'éviter les problèmes de comparaisons de version lorsque l'on utilise un gestionnaire de version type CVS.
Les conventions de codage utilisées pour LODEL sont en grande partie inspirées de celles utilisées par les développeurs de PEAR (http://www.pear.php.net/manual/fr/standards.php).
[modifier] Format et encodage des fichiers
Tous les fichiers PHP et HTML de Lodel doivent suivre les règles suivantes :
- utiliser le jeux de caractère ISO-8859-1 ;
- être stocké comme du texte ASCII ;
- être formaté UNIX ;
- les lignes doivent finir uniquement par un retour à la ligne (LF). Les retours à la ligne sont représentés par l'ordinal 10, l'octal 012 et l'hexadécimal 0A. N'utilisez par les retours « carriage » (CR) comme le font les Macintosh ou les combinaisons retour « carriage » / retour à la ligne (CRLF) comme le fait Windows.
- il ne doit y avoir qu'un seul retour à la ligne après la fermeture du tag PHP ?>. Cela signifie que lorsque le curseur est à la fin du fichier, il doit y avoir une seule ligne après le tag PHP fermant.
[modifier] Indentation et longueur de ligne
Le monde des développeurs est partagé entre l'utilisation des tabulations et des espaces pour l'indentation du code. Cette discussion historique vient du fait qu'aucun logiciel d'édition de code (de Vim à Eclipse pour en citer deux) ne gère de la même manière la longueur des tabulations. Il faut en réalité configurer soit même cette longueur. Des tabulations trop longues rendent le code illisible dans une résolution d'écran petite. Contrairement à PEAR et beaucoup d'autres projets PHP, il faut utiliser le caractère tabulation et ceci pour deux raisons :
- la tabulation représente un seul caractère (contrairement à 4 espaces) ;
- il semble logique que ce soit l'utilisateur qui adapte son environnement de travail concernant le rendu du code : coloration syntaxique, longueur des tabulations, etc.
En ce qui concerne la longueur des lignes il est recommandé qu'elles ne dépassent pas 75 à 85 caractères. Pour les retours à la ligne il n'y a pas de règles fixes mais, dans le cas de chaînes de caractères, il est préférable d'utiliser la concaténation de chaîne (caractère .) :
<?php echo "ma chaine super longue, tellement longue qu'elle dépasse la longueur maximum". " et donc que je dois la mettre sur deux lignes"; ?>
[modifier] Structures de contrôles
Les structures de contrôles incluent les 'if, for, while, swith,...' Voici un exemple de structure for incluant un if :
<?php //instruction for for ($i=0 ; $<10 ; $i++) { if ((condition1) || (condition2)) { action1; } elseif ((condition3) && (condition4)) { action2; } else { defaultaction; } } //instruction switch switch (condition) { case 1: action1; break; default: defaultaction; } ?>
Si on suit les règles typographiques, les parenthèses ouvrantes suivant une structure de contrôle doivent être séparées de celle-ci par un espace. Une parenthèse fermante sera suivie d'un espace. De la même manière, les caractères , ; utilisés dans ces conditions seront suivis d'un espace pour la virgule et le point virgule, ce dernier étant aussi précédé d'un espace.
Il faut toujours utiliser les accolades, mêmes quand elles ne sont que optionnelles. Ainsi on améliore la lisibilité du code et on réduit le risque d'erreur lors de l'ajout de nouvelles lignes.
[modifier] Appels de fonctions
Les règles typographiques s'appliquent d'une manière particulière aux appels de fonctions : entre le nom de la fonction et la parenthèse ouvrante il n'y a jamais d'espace. Cela afin d'éviter la confusion avec une structure de contrôle. Sinon les règles sont appliquées normalement.
<?php $var = foo($bar, $bar2, $bar3); ?>
Chaque signe égal est précédé et suivi d'un espace :
<?php $bip = foo($bar); ?>
[modifier] Définitions des fonctions
L'indentation des déclarations de fonction est légèrement différente de l'indentation classique : les accolades sont mises à la ligne :
<?php function foo($arg1, $arg2 = 0) { if (condition) { action; } return $val; } ?>
Les arguments d'une fonction ayant une valeur par défaut sont obligatoirement mis en fin de liste.
Une fonction doit toujours chercher à retourner une valeur lorsque c'est possible.
[modifier] Commentaires
La documentation des classes du code source doit suivre la convention PHPDoc, similaire à celle de Javadoc.
Les commentaires non inclus dans la documentation sont vivement encouragés. En citant le document de convention de PEAR (http://www.pear.php.net/manual/fr/standards.comments.php) : “si en regardant une portion du code, vous pensez << Waouh ! je ne veux pas me lancer dans cette explication >>, il faut absolument la commenter de suite avant d'oublier comment cela fonctionne”.
Les commentaires du type C/C++ (/* */ et // sont acceptés de même que #. Dans le cas d'une mise en commentaire d'une portion de code il faut utiliser /* */. Dans le cas d'une mise en commentaire d'une seule ligne de code (ligne de « debug » par exemple) il faut utiliser le signe #. Les commentaires d'explications doivent donc utiliser //.
En règle générale, veillez à ne pas non plus abuser des commentaires car ceux-ci alourdiront alors beaucoup le code source et donc la taille du fichier. Il est à noter d'ailleurs que certains projets distribuent leur code PHP en deux versions : une light sans les commentaires, destinée uniquement à être utilisée, et une version avec les commentaires, plus destinée aux personnes intéressées par le code source. Ceci est fait dans un souci de performance et une réflexion sera engagée afin de mesurer l'utilité de cette manière de faire.
[modifier] Inclure du code
Lors d'une inclusion de façon inconditionnelle d'un fichier de classe, il faut utiliser require_once. Lors d'une inclusion conditionnelle (par exemple des méthodes de construction), utilisez include_once. Ces deux méthodes s'assurent que le fichier n'est inclus qu'une seule fois et comme elles partagent la même liste de fichiers, il est possible de les mélanger.
Attention ! include_once et require_once sont des structures de contrôle et non des fonctions, elles ne doivent donc pas être entourées de parenthèses (même si le compilateur PHP les accepte).
<?php require 'fichier';?>
[modifier] Tags de code PHP
Il faut toujours utiliser <?php ?> plutôt que <? ?> afin de maximiser la portabilité du code PHP sur des systèmes d'exploitations configurés différemment.
[modifier] Commentaires d'En-tête
Les fichiers de code source doivent toujours commencer par un bloc contenant : Une courte description du fichier Une description plus détaillée si besoin Les versions de PHP compatibles Le bloc de licence (pour Lodel il s'agit de la GPL) Les balises sur le copyright, l'auteur, licence,...
[modifier] Balises requises
- @licence : adresse de la licence GPL : http://www.gnu.org/copyleft/gpl.html
- @copyright : doit correspondre à la ligne de copyright de l'année en cours.
- @author : un contributeur est généralement considéré comme auteur du code si ses modifications atteignent environ 20% du code. Mais cela est laissé à l'appréciation du responsable du code source. Les corrections de bugs ne constituent pas l'ajout d'une personne en tant qu'auteur.
- @since : cette balise est requise lorsqu'un fichier a été ajouté après la première « release ».
- @deprecated : cette balise est requise lorsqu'un fichier, une classe ou une fonction n'est plus utilisé mais a été laissé en place pour assurer la compatibilité ascendante.
[modifier] Balises optionnelles
- @see : utilisez cette balise pour renvoyer le lecteur vers d'autres parties de la documentation du code source.
- @version CVS: $Id:$
[modifier] Conventions de noms
[modifier] Classes
Les noms des classes doivent être parlant. Il doivent toujours commencer par une majuscule et éviter les abréviations.
[modifier] Fonctions et méthodes de classe
Les fonctions et méthodes doivent être nommées en utilisant le style <<studly caps>> : utilisation de majuscule en milieu de mot pour marquer visuellement la séparation entre les mots sans utiliser d'espaces ou de séparateurs. De plus les fonctions doivent avoir le nom du « package » comme préfixe, pour éviter les doublons. Voici quelques exemples valides : connect() - getData() - makeSelect()
Les éléments privés d'une classe (méthode ou attributs) sont précédés d'un seul '_'.
[modifier] Constantes
Les constantes sont à écrire en majuscule, les mots séparés par des _. Préfixez les noms des constantes avec le nom en majuscule de la classe/package dans laquelle elle est utilisé.
Attention! les constantes true, false et null font exception à la règle.
[modifier] Variables globales
Les variables globales doivent commencer par un '_' suivi du nom du package puis d'un autre '_'. Un exemple valable est : $_DB_dbname;</>
