Forums Développement Multimédia

Les formations Mediabox
Les formations Mediabox

Quelques conventions d'écriture PHP

Compatible PHP. Cliquer pour en savoir plus sur les compatibilités.Par qwix, le 08 juin 2005

Nous essayons d'adopter les conventions Pear dont vous trouverez l'intégralité ci-dessous.

Indentation et longueur de lignes

Utilisez une indentation de 4 espaces, sans tabulationis.

Il est recommandé que la longueur des lignes ne dépasse pas 75 à 85 caractères. Il n'y a pas de règles fixes par rapport aux retours à la ligne, mais vous pouvez utiliser votre bon jugement. En cas de doutes, vous pouvez toujours demander sur la liste de diffusion PEAR Quality Assurance (Ecrivez en anglais).

Structures de Contrôles

Les structures de contrôles incluent les if, for, while, switch, etc. Vous trouverez ici un exemple de structure if qui est la plus compliquée :

if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}

Les instructions de contrôle doivent avoir un espace entre le mot clé de l'instruction et la parenthèse ouvrante, afin de les distinguer des appels de fonctions.

Il est vivement recommandé de toujours utiliser des accolades, 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.

Pour l'instruction switch :

switch (condition) {
case 1:
    action1;
    break;
 
case 2:
    action2;
    break;
 
default:
    defaultaction;
    break;
}

Appels de Fonctions

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. Voici un exemple :

$var = foo($bar, $baz, $quux);

Comme montré ci-dessus, il doit y avoir un espace de chaque côté du signe égal utilisé pour affecter la valeur de retour de la fonction à une variable. Dans le cas d'un bloc d'instructions similaires, des espaces supplémentaires peuvent être ajoutés pour améliorer la lisibilité :

$short         = foo($bar);
$long_variable = foo($baz);

Définitions des fonctions

La déclaration des fonctions respecte l'indentation classique des accolades :

function fooFunction($arg1, $arg2 = '')
{
    if (condition) {
        statement;
    }
    return $val;
}

Les arguments possédant des valeurs par défaut vont à la fin de la liste des arguments. Il faut toujours chercher à retourner une valeur ayant un sens lorsque cela est possible. Voici un exemple un peu plus long :

function connect(&$dsn, $persistent = false)
{
    if (is_array($dsn)) {
        $dsninfo = &$dsn;
    } else {
        $dsninfo = DB::parseDSN($dsn);
    }
 
    if (!$dsninfo || !$dsninfo['phptype']) {
        return $this->raiseError();
    }
 
    return true;
}

Commentaires

La documentation des classes incluses dans le code source doit suivre la convention PHPDoc, similaire à celle de Javadoc. Pour plus d'information au sujet de PHPDoc, reportez-vous à : http://www.phpdoc.org/

Les commentaires non inclus dans la documentation sont vivement encouragés. La règle générale est que, si en regardant une portion de code, vous pensez « Wauouh, je ne veux pas me lancer dans cette explication », il faut absolument la commenter tout de suite avant que vous n'oubliez comment cela fonctionne.

Les commentaires du type C (/* */) et les commentaires standard C++ (//) sont tous les deux acceptés. Les commentaires de type Perl/shell (#) sont à éviter.

Inclure du Code

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

Note : include_once() et require_once() sont des instructions et non pas des fonctions. Vous ne devez pas entourer le nom du fichier avec des parenthèses.

Tags dans le Code PHP

Utilisez toujours <?php ?> pour délimiter du code PHP, et non la version abrégée <? ?>. Celà est obligatoire pour être conforme aux règles de PEAR et c'est aussi la méthode la plus portable pour inclure du code PHP sur des systèmes d'exploitations disposant de configurations différentes.

Commentaires d'En-tête

Tous les fichiers de code source qui se trouvent au coeur de la distribution PEAR doivent contenir un bloc de commentaires à propos du fichier en début, et un bloc de commentaires au dessus de chaque classe. Voici un exemple de fichier bien commenté :

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
 
/**
 * Description courte du fichier
 *
 * Description plus détaillée du fichier (si besoin en est)...
 *
 * PHP versions 4 and 5
 *
 * LICENSE: This source file is subject to version 3.0 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to license@php.net so we can mail you a copy immediately.
 *
 * @category   NomCatégorie
 * @package    NomPaquetage
 * @author     Auteur original <auteur@example.com>
 * @author     Un autre author <autre@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS: $Id:$
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      File available since Release 1.2.0
 * @deprecated File deprecated in Release 2.0.0
 */
 
/*
 * Placez ici les includes, les définitions de constantes et les configurations
 * des $_GLOBAL.
 * Assurez-vous d'ajouter les commentaires docblocks pour éviter que phpDocumen
tor
 * assume qu'elles sont documentées dans les commentaires générals du fichier.
 */
 
/**
 * Description courte de la classe
 *
 * Description plus détaillée de la classe (si besoin en est)...
 *
 * @category   NomCatégorie
 * @package    NomPaquetage
 * @author     Auteur original <auteur@example.com>
 * @author     Un autre author <autre@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    Release: @package_version@
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      Class available since Release 1.2.0
 * @deprecated Class deprecated in Release 2.0.0
 */
class foo
{
}

Balises requises ayant un contenu variable

Descriptions courtes

Les descriptions courtes doivent être fournies pour tous les commentaires docblocks. Elles doivent comporter des phrases courtes, non pas le nom de l'élément. Lisez le fichier d'exemple de la convention de codage pour avoir de bons exemples de descriptions.

Versions de PHP

Vous devez utiliser l'une des lignes suivantes dans les commentaires de la page:

  • PHP version 4
  • PHP version 5
  • PHP versions 4 and 5

@license

Il y'a plusieurs licences possibles. Choisissez-en une dans ce qui suit et placez la dans les commentaires de la page et des classes :

Pour plus d'informations, consultez PEAR Group's Licensing Announcement.

@link

Ce qui suit doit être utilisé dans les commentaires de pages et de classes. Bien sûr, changez « NomPaquetage » par le vrai nom de votre paquetage, cela permettra de générer un lien sur votre paquetage sur la documentation.

  • @link http://pear.php.net/package/NomPaquetage

@author

Il n'existe pas de vrai règle pour décider le moment où un contributeur de code doit être ajouté en tant qu'auteur. En général, leurs modifications doivent être “substentielles” (entre 10 et 20% de modifications). Des exceptions sont toutefois permises lors de la réécriture complète de fonctions ou la contribution de nouvelles approches.

La réorganisation de code ou les corrections de bogues ne justifient pas l'ajout d'une nouvelle personne en tant qu'auteur.

@since

Cette balise est requise lorsqu'un fichier ou une classe a été ajouté après la première release. N'utilisez pas cette balise pour une nouvelle release.

@deprecated

Cette balise est requise lorsqu'un fichier ou une classe n'est plus utilisé mais a été laissé en place pour assurer la compatibilité ascendante.

Balises optionnelles

@copyright Utilisez les copyrights que vous voulez. Lorsque vous formattez cette balise, l'année doit comporter quatre chiffres. Si vous voulez couvrir une période avec le copyright, utilisez un tiret entre la première et la dernière année. Vous pouvez vous placer vous-mêmes en tant que détenteur du copyright, ou une list de personnes, ou une entreprise, ou le PHP Group, etc. Exemples :

  • @copyright 2003 John Doe and Jennifer Buck
  • @copyright 2001-2004 John Doe
  • @copyright 1997-2004 The PHP Group
  • @copyright 2001-2004 AFUP

Description de la licence

Si vous utilisez la licence PHP, utilisez la description fournie plus haut. Si une autre licence est utilisée, merci de supprimer la description de la licence PHP. Vous pouvez y placer votre propre description en prenant soin de préfixer le texte par LICENSE: pour faciliter sa localisation.

@see

Ajoutez une balise @see quand vous voulez envoyer les utilisateurs vers d'autres sections de la documentation du paquetage. Si vous avez plusieurs éléments, séparez les avec des virgules plutôt que d'ajouter d'autre balises @see.

Ordre et espacement

Pour faciliter la lisibilité à long terme de vos codes sources PEAR, les textes et les balises doivent se conformer à l'ordre et aux emplacements utilisés dans l'exemple précédent. Ce standard a été adopté à partit du standard JavaDoc.


Tutorial de Qwix