Voilà, voilà... Fin de l'aventure...

 

Fermeture de kolossaldrupal.org dans...


Bonjour tout le monde,

Drupal évolue, les versions changent et Kolossaldrupal.org était essentiellement consacré à la version 6 de Drupal.

Autant dire que les infos présentées ici commencent à dater...

Faute de temps, je ne peux plus garder le site Kolossaldrupal à jour...

Je vous aurais bien proposé de reprendre le flambeau mais... c'est tellement simple de nos jours de se faire son propre site à soi...Pourquoi s'embêter alors ? :-)

Ce site restera donc en l'état, tel qu'il était en 2011...

Ah la la ! Cela ne nous rajeunit pas !

Manuel Vila - Avril 2016

Normes de programmation

Référence sur drupal.org : 8 Juin 2009 – 15h51 - http://drupal.org/coding-standards


Remarque : les Normes de programmation de Drupal s’appliquent au code de Drupal et à celui des modules tiers. Ce document est basé sur les normes de codage PEAR. Les commentaires et les noms devraient utiliser l’orthographe anglo-américaine (« color » et non pas « colour », etc).

Contenu de la page

Indentation

Utilisez une indentation de 2 espaces, pas de tabulations.

Pas d’espace après le dernier mot de la ligne.

Les lignes doivent être formatées avec un \n en fin de ligne (fins de ligne Unix), pas de \r\n (fins de lignes Windows).

Opérateurs

Tous les opérateurs tels que +, -, =, !=, ==, >,  etc, doivent avoir une espace avant et après l’opérateur, pour améliorer la lisibilité.

Par exemple, une affectation doit être formatée $foo = $bar; au lieu de $foo=$bar;.

Structures de contrôle

Cela concerne if, for, while, switch, etc. Voici un exemple de déclaration IF, puisque c’est une des plus complexe :

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

Les déclaration de structures de contrôle devraient avoir une espace entre le mot-clé et la parenthèse ouvrante, afin de les distinguer des appels de fonctions.

Vous êtes fortement encouragés à toujours utiliser les accolades, même dans les cas où elles seraient techniquement facultatives. Ceci accroît la lisibilité et réduit les risques d’erreurs de logique qui peuvent apparaître avec l’ajout de nouvelles lignes.

Pour les déclarations switch :

switch ($nomdevariable) {
  case 1:
    action1;
    break;

  case 2:
    action2;
    break;

  default:
    defaultaction;
}

Appels de fonctions

Les fonctions devraient être appelées sans espace entre le nom de la fonction, la parenthèse ouvrante, et le premier paramètre; espaces entre les virgules et chaque paramètre, la parenthèse fermante, le point-virgule. Voici un exemple :

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

Comme affiché plus haut, il devrait y avoir une espace de part et d’autre du signe égal utilisé pour affecter la valeur de retour de la fonction à la variable. Dans le cas de blocs comportant plusieurs affectations, plus d’espaces peuvent être insérées afin d’accroître la lisbilité :

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

Déclaration de fonctions

function funstuff_system($field) {
  $system["description"] = t("Ce module insère du texte rigolo dans les publications, au hasard.");
  return $system[$field];
}

Les arguments ayant des valeurs par défaut se trouvent en dernières positions de la liste d’arguments. Tentez toujours de retourner une valeur d’une fonction s’il en existe d’adéquate.

Tableaux

Les tableaux devraient être formatés avec une espace séparant chaque élément et opérateur d’affectation, si le tableau le permet :

$some_array = array('hello', 'world', 'foo' => 'bar');

Notez que si la ligne dépasse 80 caractères (ce qui est souvent le cas pour la déclaration  d’un formulaire ou d’un menu) chaque élément devrait être disposé dans sa propre ligne, et indenter d’un niveau :

$form['title'] = array(
  '#type' => 'textfield',
  '#title' => t('Titre'),
  '#size' => 60,
  '#maxlength' => 128,
  '#description' => t('Le titre de votre node.'),
);

Notez la virgule après les dernier élément du tableau. Ce n’est pas de la typographie ! Cela évite des erreurs de parsing si un autre élément est ultérieurement placé en fin de liste.

Guillemets

Les guillemets simples et doubles sont des caractéristiques de PHP pour faciliter la programmation et il n’y a pas de raisons qui feraient préférer les uns ou les autres. Cette pratique est laissée à l’appréciation du programmeur. Quand c’est possible, soyez cohérents dans tous vos modules et respectez le style des autres développeurs.

Avec cette mise en garde : les guillemets simples sont connus pour être plus rapides puisque le parser n’a pas à recherche des variables dedans. Leur utilisation est recommandée sauf dans deux cas :

1.utilisation de variables à l’intérieur des guillemets

2.Chaînes traduites où l’on peut éviter l’échappement des guillemets simples en encadrant la chaîne de doubles guillemets. Une chaîne de ce type « C’est un bon gars » deviendrait ’C\’est un bon gars » avec des guillemets simples. Ce type d’échappement pourrait ne pas être correctement géré par les générateurs de fichiers de traductions .pot.

Concaténation de chaînes

Pour améliorer la lisibilité, utilisez toujours une espace entre le point et les chaînes à concaténer :

<?php
  $string 
'Foo' $bar;
  
$string $bar 'foo';
  
$string bar() . 'foo';
  
$string 'foo' 'bar';
?>

Quand vous concaténez des variables simples, vous pouvez utiliser de guillemets doubles et ajouter la chaîne dedans, sinon utilisez des guillemets simples.

<?php
  $string 
"Foo $bar";
?>

Quand vous utilisez l’opérateur de concaténation .=, utilisez une espace de part et d’autre, comme pour le signe égal :

<?php
$string 
.= 'Foo';
$string .= $bar;
$string .= baz();
?>

Commentaires

La documentation au sein du code-source devrait respecter les normes de formatage Doxygen.

Les commentaires divers sont fortement encouragés. Une règle générale dit que si vous regardez une portion de code et vous exclamez « La vache ! Je ne veux pas essayer d’expliquer ça ! », alors vous devez commenter le code avant d’oublier comment il marche.

Les commentaires divers devraient utiliser des phrases avec des majuscules et ponctuées. Les phrases devraient être séparées par des espaces simples. Les lettres ne doivent être en capitales que pour désigner les constantes, par exemple : TRUE. Les commentaires devraient être sur une ligne à part juste avant la ligne de code ou le bloc de code qu’ils désignent. Par exemple :

// Unselect all other contact categories.
db_query('UPDATE {contact} SET selected = 0');

Si chaque ligne d’une liste a besoin d’un commentaire, ils peuvent être placés sur la même ligne et indentés de façon uniforme pour une meilleure lisibilité.

Les commentaires comme en C /* */ et en C++ // sont valables. L’utilisation de commentaires à la façon Perl/shell # sont déconseillés.

Inclusion de code

Quel que soit l’endroit où vous incluez un fichier de classe inconditionnellement, utilisez require_once().

Quel que soit l’endroit où vous incluez un fichier de classes conditionnellement (par exemple, pour des factory methods), utilisez include_once().

Chacune de ces instructions fera en sorte que les fichiers classes ne soient inclus qu’une fois. Elles partagent la même liste de fichiers ce qui fait que vous pouvez les mélanger sans crainte – un fichier inclus avec require_once() ne sera pas à nouveau inclus avec include_once().

Remarque : include_once() et require_once() dont des instructions, pas des fonctions. Vous n’avez pas besoin des parenthèses autour du nom de fichier à inclure.

Lorsque vous incluez du code du même dossier ou d’un sous-dossier, commencez le chemin du fichier avec . :

include_once ./includes/mymodule_formatting.inc

Dans Drupal 7.x et ultérieur, utilisez DRUPAL_ROOT :

require_once DRUPAL_ROOT . '/' . variable_get('cache_inc', 'includes/cache.inc');

Balises PHP

Utilisez toujours <?php ?> pour délimiter le code PHP, pas le raccourci <? ?>. C’est exigé  pour la conformité avec Drupal et c’est aussi la façon la plus portable d’inclure du code PHP sur différents systèmes d’exploitation ou configurations.

Notez qu’à compter de Drupal 4.7, le ?> à la fin du code est volontairement omis. Cela concerne les modules et les fichiers inclus. En voici brièvement les raisons :

  • Cette suppression élimine le risque d’espaces involontaires à la fin des fichiers, qui peuvent causer l’erreur « Header already sent », des problèmes de validation XHTML/XML, et d’autres soucis.
  • La balise de fermeture en fin de fichier est facultative.
  • PHP.NET lui-même omet la balise de fin (exemple : prepend.inc) on peut donc le considérer comme une « bonne pratique ».

Points-virgules

Le langage PHP exige la présence de points-virgules à la fin de la plupart des lignes mais permet leur omission à la fin d’un bloc de code.

Les normes de programmation Drupal les exigent, même à la fin d’un bloc de code. En particulier pour les blocs d’une seule ligne :


<?php print $tax?> -- YES
<?php print $tax ?> -- NO
?>

En-tête CVS

Tout code source du core de Drupal devrait contenir le bloc de commentaire suivant en en-tête :

<?php
// $Id$

Cette étiquette sera complétée avec des infos utiles par le CVS :

<?php
// $Id: CODING_STANDARDS.html,v 1.15 2008/12/22 15:27:26 keithsmith Exp $

Modèles d’URL

Utilisez « example.com » pour toutes les exemples d’URL, comme expliqué dans RFC 2006.

Conventions de nommage

Fonctions

Les noms de fonctions doivent être en minuscules et les mots séparés par un signe souligné. De plus, le nom du module doit préfixer le nom, pour éviter les conflits entre les modules.

Les membres de classes privées (c’est à dire les membres de classes destinées à n’être utilisées que dans la classe où ils sont déclarés) sont précédés par un signe souligné unique. Par exemple :

_node_get()

$this->_status

Constantes

Les constantes doivent toujours êtres écrites en majuscules, avec un signe souligné » séparant les mots. Cela concerne les constantes pré-déclarées de PHP, comme TRU, FLASE et NULL. Les constantes déclarées dans les modules doivent aussi être préfixées par le nom du module où elles sont déclarées, en majuscules.

Variables globales

Si vous avez besoin de définir des variables globales, leur nom doit commencer par un signe souligné unique, suivi du nom du thème ou du module et d’un autre signe souligné.

Noms des classes

Les classes doivent être nommées en utilisant le style CamelCase. Par exemple :

<?php
abstract class DatabaseConnection extends PDO {
?>

Les méthodes de classe et les propriétés doivent utiliser le style lowerCamelCase

<?php
public $lastStatement;
?>

Noms de fichiers

Tous les fichiers de documentation doivent porter l’extension .txt pour pouvoir les repérer facilement sur un système Windows. De même, les noms de ces fichiers doivent être entièrement en capitales (par exemple : README.txt au lieu de readme.txt), tandis que l’extension doit toujours être en minuscules (c’est à dire .txt au lieu de .TXT).

Exemples : README.txt, INSTALL.txt, TODO.txt, CHANGELOG.txt etc.

Script d’aide

Drupal dispose d’un script en ligne de commande pour vérifier si votre code satisfait aux normes de codage. Le fichier code-style.pl est situé dans le dossiers /scripts. Pour l’utiliser, indiquez simplement votre fichier en argument (assurez-vous que le script soit exécutable :

./code-style.pl path/to/file/example.module

Vous obtiendrez une liste de propositions sur les endroits de votre code à améliorer. Vous devrez effectuer ces modifications vous-même.

Module d’aide

Il existe un module qui vous assiste dans les révisions du code. Pour l’utiliser, effectuez les opérations suivantes :

  • Installez le module Coder
  • Cliquez sur le lien « Code Review » de votre menu de navigation
  • Déroulez jusqu’à « Sélectionnez les modules spécifiques »
  • Sélectionnez le module à réviser et cliquez sur le bouton Submit