Ébauche des normes de codage de XOOPS 3.0

• Taiwen Jiang <phppp@users.sourceforge.net>
  

Portée

Ce document fournit les normes et les directives de codage pour les développeurs et les équipes travaillant sur ou avec le projet XOOPS. Les sujets traités sont :

• Formatage des fichiers PHP
• Conventions de nommage
• Règles de codage
• Documentation intégrée
• Erreurs et exceptions
  

• Développeurs XOOPS : Développeurs qui contribuent aux 'frameworks' XOOPS, incluant
  
• Développeurs du noyau : Développeurs qui contribuent au SVN du noyau de XOOPS et dont le code sera employé par des développeurs d'application XOOPS.
  
• Développeurs du 'framework' : Développeurs qui contribuent aux 'frameworks' de XOOPS qui pourraient être adoptés dans le noyau de XOOPS à l'avenir.
• Développeurs d'interface utilisateur : Développeurs qui travaillent sur les thèmes de XOOPS et les 'templates' de modules.
• Créateurs d'applications XOOPS : Développeurs qui créent leurs propres applications sur la plate-forme XOOPS
• Développeurs de modules : Développeurs qui construisent des modules tiers utilisant la plate-forme et les bibliothèques XOOPS.

Objectifs

De bonnes normes de codage sont importantes dans n'importe quel projet de développement, en particulier lorsque plusieurs développeurs travaillent sur un même projet. Avoir des normes de codage aide à s'assurer que le code est de qualité, a peu de bogues et est facile à maintenir.

Les buts abstraits que nous poursuivons :

• simplicité extrême
• outil convivial, à travers l'utilisation des signatures de méthode, constantes et modèles qui soutiennent des outils d'IDE et les propositions automatisées lors de la saisie de nom de méthode, de classe et noms de constantes.

Au vu des buts ci-dessus, chaque situation exige un examen des circonstances et de l'équilibrage des compromis.

Formatage des fichiers PHP

Généralités

Pour les fichiers qui contiennent du code PHP, le tag fermant (" ? >") doit être inclus lorsque c'est nécessaire.

Indentation

Employez une indentation de 4 espaces, sans tabulation. Les éditeurs de texte doivent être configurés pour convertir les tabulations en quatre espaces afin d'empêcher l'injection de tabulations dans le code source.

Longueur maximale des lignes

L'ojectif de longueur de ligne à respecter est de 80 caractères ; c'est-à-dire que les développeurs doivent s'appliquer à conserver le code aussi près que possible de la barrière de 80 colonnes. Cependant, de plus longues lignes sont acceptables. La longueur maximale de n'importe quelle ligne de code de PHP est de 120 caractères.

Fin de Ligne

La fin de ligne est la méthode standard pour les fichiers textes sous Unix. Les lignes doivent se finir avec un retour à la ligne (LF). Les retours à la ligne sont représentés comme le nombre ordinal 10, ou 0x0A en hexadécimal.

N'employez pas les retours chariot (CR) comme les ordinateurs Macintosh (0x0D).

N'employez pas le retour de chariot/retour à la ligne (CRLF) comme les ordinateurs Windows (0x0D, 0x0A).

Les lignes ne doivent pas contenir d'espaces en fin de ligne. Afin de faciliter cette convention, la plupart des éditeurs peuvent être configurés pour supprimer les espaces en fin de ligne lors de la sauvegarde du fichier.

Conventions de nommage

Proposition globale

1. Les noms pour toutes les classes et fonctions à l'intérieur de XOOPS doivent commencer par Xoops ;
1. La première lettre des noms de fonction doit toujours être en minuscule; si nécessaire les noms doivent être séparés en utilisant des tirets bas « _ », pas de CamelCaps (explication sur CamelCaps en bas de cette page):
• les fonctions du noyau doivent commencer par xoops_
• le 'framework' et les fonctions de bibliothèque doivent commencer par xoops_ ['framework' ou identifiant de bibliothèque]_
  
2. Les noms de classe doivent toujours être séparés en utilisant des CamelCaps (explications sur CamelCaps en bas de cette page);
   
2. Les noms des variables partagées, produites par XOOPS doivent commencer par $xoops suivi de CamelCaps.
   
• Pour les variables privées (ou non partagées) nous vous encourageons à suivre le même modèle
3. Les applications tierces, y compris les modules, ne doivent pas commencer par Xoops_ mais par le préfixe de l'application
• Les noms de classe de modules doivent commencer par [identifiant du module, habituellement nom de répertoire] en respectant le style CamelCaps, par exemple NewbbPost
  
• Les noms de fonctions de modules doivent commencer par [identifiant du module, habituellement nom de répertoire] _ , par exemple newbb_getPostCount ()
  
• Les variables de modules doivent commencer par $[identifiant du module], par exemple $newbbPostCount

Abstractions utilisées dans les api (interfaces de classes)

En créant une API à l'usage des développeurs d'application, si les développeurs d'application doivent identifier des abstractions en utilisant un nom composé, séparez les noms en utilisant des tirets bas (underscore), pas les CamelCaps.Quand le développeur emploie une chaine de caractères, il faut la normaliser en lettres minuscules. Lorsque cela est possible, utilisez des constantes.

Classes

Interfaces

Les classes d'interface doivent suivre les mêmes conventions que les autres classes (voir ci-dessus), mais doivent finir avec «_Interface», comme : XoopsLogger_Interface

Noms des fichiers

Pour tous les fichiers, seuls les caractères alphanumériques, les tirets bas et le tiret haut(« - ») sont autorisés. Les espaces sont interdits.

N'importe quel fichier contenant du code PHP doit finir avec l'extension «  .php  ».

Noms des dossiers

Pour tous les dossiers, seuls les caractères alphanumériques, les tirets bas et le tiret haut(« - ») sont autorisés. Les espaces sont interdits.

Fonctions et méthodes

Le nom des fonctions du noyau et du module système doivent commencer par xoops_doSomething ([...]) .

Les noms des fonctions du 'framework' doivent commencer par  xoops_ [identifiant en minuscule], comme xoops_pear_doSomething ([...]) .

Les noms des fonctions de modules doivent commencer par [identifiant du module en minuscule]_ , comme newbb_getTopic ([...]) .

• Les noms de fonction doivent seulement contenir les caractères alphanumériques et les tirets bas. Les nombres sont autorisés dans des noms de fonctions, mais ne sont pas recommandés.
• Les noms de fonction doivent toujours commencer par une lettre minuscule.
  
• La clarté est encouragée. Les noms de fonction doivent être aussi parlant que nécessaire pour augmenter la compréhension.
• Pour la programmation orientée objet, les méthodes d'accès doivent toujours être préfixées avec ou «  get  » ou «  set  ».
• Les méthodes de classes qui sont déclarées comme protégées ou privées sont encouragées à suivre le même modèle que les méthodes publiques bien que certains 'frameworks' externes nécessitent de commencer par un tiret bas (underscore).
• Des fonctions de portée globale, ou « fonctions flottantes» sont autorisées mais non recommandées. Nous recommandons que ces fonctions soient embarquées dans une classe et déclarées comme étant statiques.
• Les méthodes ou les variables déclarés avec une portée «  statique  » dans une classe en général, ne doivent pas être «  privées  », mais plutôt "protégées". Employez «  final  » si la méthode ne peut pas être étendue.

Paramètres optionnels

Employez «  NULL  » comme valeur par défaut au lieu de «  FALSE  », pour des situations comme ceci :

public function foo($required, $optional = NULL)

quand $optional n'a pas ou n'a pas besoin d'une valeur par défaut particulière.

Cependant, si un paramètre facultatif est booléen, et que sa valeur par défaut logique devrait être vrai, ou faux, l'utilisation de vrai ou faux est acceptable.

Variables

• Les variables globales systèmes doivent commencer par $xoops , comme $xoopsConfig
• Les variables globales de modules doivent commencer par $[identifiant du module en lettre minuscule] suivi du style camelCaps, comme $newbbPostCounter
• Noms de variables pour les 'frameworks/bibliothèques' tiers
  

• Les noms variables contiennent habituellement seulement des caractères alphanumériques. Les tirets bas et les nombres sont autorisés dans des noms variables mais ne sont pas recommandés.
• Les variables de classe déclarées « public » ne doivent jamais commencer par un tiret bas.
• Pour les variables de classe déclarées comme 'protected' ou 'private' nous vous encourageons à suivre le même modèle que les variables publiques, cest-à-dire sans tiret bas au début.
• Comme les noms de fonction, les noms de variables doivent toujours commencer par une lettre minuscule et suivre la convention de nommage « CamelCaps ».
• La clarté est encouragée. Les noms variables doivent être aussi parlant que nécessaire pour augmenter la compréhension. Des noms de variables laconiques tels que «  $i  » et «  $n  » sont uniquement conseillé pour un compteur dans une boucle. Si une boucle contient plus de 20 lignes de code, les variables pour de tels index ou compteurs doivent avoir des noms plus descriptifs.

Constantes

Variables

Les constantes  système commencent par XOOPS_ : XOOPS_URL

Les constantes de 'framework' doivent commencer par  XOOPS_ [identifiant] : XOOPS_PEAR_CONSTANT

Les constantes de module doivent commencer par [identifiant du module]_ : NEWBB_CONSTANT

Définitions de langue 

Commencez toujours par le tiret bas : _XOOPS_LANGUAGE_CONSTANT , _NEWBB_LANGUAGE_CONSTANT

• Les constantes peuvent contenir des caractères alphanumériques et le tiret bas. Les nombres sont autorisés dans les noms de constantes.
• Les noms de constantes doivent toujours être en majuscules.
• Pour améliorer la lisibilité, les mots dans les noms de constantes doivent être séparés par des tiret bas. Par exemple, «  XOOPS_EMBED_SUPPRESS_EMBED_EXCEPTION  » est autorisé mais «  XOOPS_EMBED_SUPPRESSEMBEDEXCEPTION  » n'est pas autorisé.
• Des constantes doivent être définies comme membres de classe en employant le constructeur «  const  ». Les constantes de portée globale  définies en utilisant «  define  » sont autorisées mais non recommandées.

Booléens et la valeur NULL

Comme dans la documentation PHP, XOOPS utilise les lettres capitales pour les valeurs booléennes et la valeur «  NULL ».

Noms des 'templates' de modules

Modèle de codage

Délimiteur de code PHP

Le code PHP à l'intérieur de XOOPS doit toujours être délimité par les étiquettes complétes standard de PHP :

<?php

? >

Les tags courts ne sont jamais autorisées.

Chaînes

Constantes de chaîne

Les doubles « guillemets » ou le simple guillemet « apostrophe » sont autorisés pour une chaine qui est littérale (ne contient aucune substitution de variable) , l'« apostrophe » est encouragé :

$a = 'chaine exemple' ;

Constantes de chaîne contenant des apostrophes

Quand une chaine littérale contient des apostrophes, elle est autorisée à délimiter la chaine avec des « guillemets ». Ceci est particulièrement encouragé pour des commandes SQL :

$sql= "`SELECT 'id', `name` from `people` WHERE `name'= 'Fred' OR`name' = 'Susan'" ;

La syntaxe ci-dessus est préférable à l'échappement des apostrophes.

Substitution de variable

La substitution de variable est encouragée en utilisant le crochet .

$greeting = "bonjour $name, bienvenue !" ;

Pour l'uniformité, cette notation n'est pas autorisée :

$greeting = "bonjour ${nom}, bienvenue !";

Concaténation de chaine

Des chaines peuvent être concaténées en utilisant l'opérateur " . ". Un espace doit toujours être ajouté avant et après " . "  pour améliorer la lisibilité :

$project = 'Xoops' . ' ' . 'Project';

Lors de la concaténation de chaînes avec l'opérateur " . ", il est permis d'écrire l'instruction sur plusieurs lignes pour améliorer la lisibilité. Dans ces cas, chaque ligne doit être complétée avec des espaces de telle sorte que l'opérateur  " . " soit aligné sous l'opérateur " = " :

   $sql = "SELECT `id`, `name` FROM `people` " "
           . "WHERE `name` = 'Susan' " "
           . "ORDER BY `name` ASC ";

Tableaux

Tableau à index numérique

Les nombres négatifs ne sont pas autorisés comme index de tableau.

Un tableau indexé peut commencer par tout nombre non négatif, toutefois ceci n'est pas recommandé. Nous recommandons que tous les tableaux aient un index commençant à 0.

Lors de la déclaration de tableau indexé via le constructeur de tableau, un caractère d'espacement doit être ajouté après chaque virgule pour améliorer la lisibilité :

$sampleArray = array(1, 2, 3, 'XOOPS', 'Project');

Il est également autorisé de déclarer des tableaux indexés sur plusieurs lignes via le constructeur de tableau. Dans ce cas, chaque ligne doit être complétée avec des espaces de telle sorte que les lignes respectent l'alignement ci-dessous :

    $sampleArray = array(1, 2, 3, 'XOOPS', 'Project',
                                 $a, $b, $c,
                                 56.44, $d, 500);

Tableaux associatifs

En déclarant des tableaux associatifs via le constructeur de tableau, il est préférable de déclarer le tableau sur plusieurs lignes. Dans ce cas, chaque ligne successive doit être complétée avec des espaces de telle sorte que les clefs et les valeurs soient alignées :

$sampleArray = array('firstKey'        => 'firstValue',
                             'secondKey'    => 'secondValue');

Classes

Déclarations de classes

Des classes doivent être appelées en suivant les conventions de nommage.

L'accolade est toujours écrite sur la ligne, juste sous le nom de la classe.

Chaque classe doit avoir un bloc de documentation qui se conforme à la norme de phpDocumentor .

Le code dans une classe doit être indenté avec le standard des quatre espaces.

Il est recommmandé d'écrire une seule classe par fichier PHP.

L'écriture de code additionnel dans un fichier de classe est autorisé mais non recommandé. Deux interlignes doivent séparer la classe du code additionnel dans le fichier PHP.

Voici un exemple de déclaration acceptable de classe :

/**
 * Class Docblock Here
 */
class XoopsClass
{
    // entire content of class
    // must be indented four spaces
}

Variables de classe

Des variables de classe doivent suivre les conventions de nommage.

Toutes les variables de classe doivent être déclarées au début de la classe, avant avant la déclaration de toute fonction.

Le constructeur 'var' n'est pas autorisée. Les variables de classe définissent toujours leur visibilité en employant une des constructeurs 'private', 'protected', ou 'public'. L'accès aux variables directement en les rendant publique est autorisé, dans certains cas, c'est en faveur de méthodes d'accès ayant les préfixes set / get.    

Fonctions et méthodes

Déclaration de fonctions et de méthodes

Les fonctions et les méthodes de classes doivent être créées en suivant les conventions de nommage.

Les méthodes doivent toujours déclarer leur visibilité en employant une des constructeurs ' private', 'protected', 'public'.

L'usage dans la communauté PHP, consiste à déclarer les méthodes statiques en premier :

public      static foo()    { ... }
private     static bar()    { ... }
protected   static goo()    { ... }

Comme pour les classes, l'accolade d'ouverture pour une fonction ou une méthode est toujours écrite sur une ligne juste sous le nom de fonction ou de méthode. Il n'y a aucun espace entre le nom de fonction ou de méthode et la parenthèse d'ouverture pour les arguments.

Voici un exemple acceptable de déclaration de méthode :

/**
 * Class Docblock Here
 */
class XoopsFoo
{
    /**
     * Method Docblock Here
     */
    public function sampleMethod($a)
    {
        // entire content of function
        // must be indented four spaces
    }
    
    /**
     * Method Docblock Here
     */
    protected function _anotherMethod()
    {
        // ...
    }
}

La valeur de retour ne doit pas être incluse entre parenthèses. Ceci peut gêner la lisibilité et peut également modifier le code si une fonction ou une méthode est ultérieurement modifiée pour obtenir une valeur de retour par référence.

function foo()
{
    // WRONG
    return($this->bar);
 
    // RIGHT
    return $this->bar;
}

L'utilisation du "type hinting" est encouragé lorsque c'est possible. Par exemple,

class XoopsComponent
{
    public function foo(SomeInterface $object)
    {}
 
    public function bar(array $options)
    {}
}

Utilisation des fonctions et méthodes

Les fonctions de portée globale sont fortement déconseillées.

Les arguments de fonction sont séparés par un espace simple après la virgule. Voici un exemple acceptable d'un appel de fonction pour une fonction qui prend trois arguments :

threeArguments (1, 2, 3) ;

Call-time pass by-reference est interdit. Pass-by-reference est autorisé dans la déclaration de fonctions seulement. Des arguments à passer par référence doivent être définis dans la déclaration de fonction.

Pour les fonctions dont les arguments permettent des tableaux, l'appel de fonction peut inclure le constructeur de " array " et peut être coupé en plusieurs lignes pour améliorer la lisibilité. Dans ce cas, les normes pour l'écriture des tableaux s'appliquent :

threeArguments(array(1, 2, 3), 2, 3);
 
threeArguments(array(1, 2, 3, 'XOOPS', 'Project',
                              $a, $b, $c,
                              56.44, $d, 500), 2, 3) ;

Instructions de contrôle

If / Else / Elseif

Les instructions de contrôle basées sur les constructeurs " if ", " else  ", et le " elseif " doivent avoir un espace simple avant la parenthèse ouvrante de la condition, et espace simple entre la parenthèse fermante et l'accolade.

Dans les instructions conditionnelles, à l'intérieur des parenthèses, les opérateurs doivent être séparés par des espaces pour plus de lisibilité. Les parenthèses sont conseillées pour améliorer la logique de groupement des longues conditions.

L'accolade d'ouverture est écrite sur la même ligne que l'instruction de condition. L'accolade de fermeture est toujours écrite sur sa propre ligne. Le contenu à l'intérieur des accolades doit être indenté à l'aide de 4 espaces.

si ($a ! = 2) {
    $a = 2 ;
}

Pour les instructions "if" qui incluent "elseif" ou "else", le formattage doit être comme dans ces exemples :

if ($a != 2) {
    $a = 2;
} else {
   $a = 7;
}  
 
if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
   $a = 4;
} else {
   $a = 7;
}

PHP autorise quelquefois ces instructions à être écrites sans accolades. Les normes de codage ne font pas de différence et toutes les instructions "if", "elseif", ou "else" doivent utiliser les accolades.

Switch

Les instructions de contrôle, écrites avec le constructeur "switch" doivent avoir un espace simple avant la parenthèse ouvrante de l'instruction de condition, ainsi qu'un espace simple entre la parenthèse fermante et l'accolade ouvrante.

Les instructions "case" à l'intérieur du "switch" ne doivent pas être indentées. Le contenu à l'intérieur de chaque instruction "case" doit être indenté avec 4 espaces.

switch ($numPeople) {
case 1:
    break;

case 2:
    break;

default:
    break;
}

Le constructeur "default" ne doit jamais être oublié dans une instruction "switch".

Documentation intégrée

Format de documentation

Tous les blocs de documentation (" docblocks ") doivent être compatibles avec le format de phpDocumentor. Pour plus d'information, visitez http://phpdoc.org

Tout le code source écrit pour la plate-forme XOOPS ou opérant avec cette plateforme doivent contenir un "file-level docblock" tout en haut de chaque fichier et un"class-level docblock" juste au-dessus de chaque classe.

Le dièse, ' # ', ne doit pas être employé pour commencer un commentaire.

Fichiers

Chaque fichier contenant du code PHP doit avoir au début du fichier, un bloc d'en-tête contenant au moins ces tags de phpDocumentor :

/**

 * Short description for file

 *

 * Long description for file (if any)...

 *
 * LICENSE
 *
 * You may not change or alter any portion of this comment or credits

 * of supporting developers from this source code or any supporting source code

 * which is considered copyrighted (c) material of the original comment or credit authors.
 *
 * @copyright   The XOOPS Project http://sourceforge.net/projects/xoops/

 * @license       http://www.fsf.org/copyleft/gpl.html GNU public license

 * @author       Author  Name <author email, or website>

 * @version      $Id$

 * @since         File available since Release 3.0.0

 */

Classes

Chaque classe doit avoir un docblock qui contient au moins ces tags de phpDocumentor :

/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @copyright   The XOOPS Project http://sourceforge.net/projects/xoops/
 * @license       http://www.fsf.org/copyleft/gpl.html GNU public license
 * @author       Author  Name <author email, or website>
 * @version      $Id$
 * @since         File available since Release 3.0.0
 */

Fonctions

Chaque fonction, y compris des méthodes d'objet, doit avoir un docblock qui contient au moins :

• Une description de la fonction
• Tous les arguments
• Toutes les valeurs de retour possibles
  

Require / Include

Si un composant emploie un autre composant, alors le composant utilisé est responsable du chargement de l'autre composant. Si l'utilisation est conditionnelle, alors le chargement devrait également être conditionnel.

Si le(s) fichier(s) pour l'autre composant doivent toujours être chargés avec succès, indépendamment de l'entrée, alors utiliser l'instruction PHP require_once .
Utiliser XoopsLoad::load() pour charger les classes configurées.

Les instructions include, include_once, require, et require_once ne doivent pas utiliser de parenthèses.

Erreurs et exceptions

Le code du projet de XOOPS doit être conforme E_STRICT. Le code de XOOPS ne doit pas émettre d'avertissement de PHP ( E_WARNING , E_USER_WARNING ), notice ( E_NOTICE , E_USER_NOTICE ), ou strict ( E_STRICT ) quand la variable "error_reporting" est initialisée à E_ALL | E_STRICT.

Voir sur http://www.php.net/errorfunc/ pour plus d'information sur E_STRICT.

Le code de XOOPS ne doit pas afficher des erreurs de PHP, si c'est raisonnablement possible. Au lieu de cela, indiquez chaque erreur avec les messages signicatifs en utilisant la fonction XOOPS "trigger_error" puis XOOPS utilisera le gestionnaire d'erreur personnalisé pour effectuer le traitement ultérieur.

1. camelCaps - Lorsqu'une chaîne est composée de plus d'un mot, la première lettre de chaque nouveau mot doit être mise en majuscule. Ceci est couramment appelé la méthode "camelCaps".