Quelles sont les normes de codage Drupal et comment les utiliser dans votre travail quotidien ?

01.04.2022

La standardisation a un effet positif sur toute entreprise. Il existe certaines normes de codage dans l'industrie du logiciel qui sont nécessaires pour réussir le développement logiciel. Les normes de codage sont un ensemble de règles et de bonnes pratiques qui rendent le code plus lisible et plus facile à développer. Dans cet article, nous présenterons quelles normes sont utilisées pour créer des projets Drupal. Nous vous montrerons les aspects de base qui méritent d'être pris en compte et les outils qui facilitent le travail.

Normes de codage dans Drupal

La communauté Drupal définit un ensemble de normes de codage et de bonnes pratiques à suivre lors de l'écriture de code. Elles sont en partie basées sur les normes de codage PEAR. Les nouvelles normes de codage proposées par la communauté sont d'abord discutées dans le projet Coding Standards.

Les normes de codage dans Drupal sont indépendantes de la version de Drupal sur laquelle nous travaillons actuellement. Tout nouveau code doit suivre les règles actuelles. Nous pouvons trouver toutes les informations sur les normes de codage dans Drupal sur le site officiel de Drupal.

Tableau

Les tableaux doivent être formatés en utilisant une syntaxe courte avec des espaces séparant chaque élément après une virgule. Nous devons ajouter des espaces avant et après l'opérateur d'affectation “=>”.

$some_array = ['hello', 'world', 'foo' => 'bar'];

Si la déclaration de tableau dépasse 80 caractères, nous devrions la découper en plusieurs lignes.

$form['title'] = [
  '#type' => 'textfield',
  '#title' => t('Title'),
  '#size' => 60,
  '#maxlength' => 128,
  '#description' => t('The title of your node.'),
];

Notez la virgule sur la dernière ligne – ce n'est pas une erreur. De cette façon, nous pouvons éviter les erreurs lors de l'ajout de nouveaux éléments au tableau à l'avenir.

Attention ! La syntaxe courte est disponible dans PHP à partir de la version 5.4. Dans les versions plus anciennes, nous devrions utiliser la syntaxe longue.

If else

La structure if else se présente comme dans l'exemple ci-dessous. Notez la disposition des parenthèses, des espaces et des accolades. Les instructions de contrôle doivent avoir un espace entre la condition et la parenthèse ouvrante.

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

Attention ! N'utilisez jamais else if. Vous pouvez utiliser elseif à la place.

Switch

Nous devrions toujours utiliser des parenthèses rondes dans les instructions de contrôle, même lorsqu'elles sont techniquement optionnelles, comme dans l'instruction switch. Cela rend le code plus lisible.

switch (condition) {
  case 1:
    action1;
    break;

  case 2:
    action2;
    break;

  default:
    defaultaction;
}

Do while

Ci-dessous, nous montrons un exemple de l'instruction de contrôle do while. Nous ajoutons un espace entre le do et la parenthèse ouvrante. La condition doit être sur la même ligne que la parenthèse fermante de l'instruction, séparée par un espace.

do {
  actions;
} while ($condition);

Longueur de la ligne de code

Chaque ligne de code ne doit pas dépasser 80 caractères. L'exception peut être une fonction, une classe ou une déclaration de variable avec un nom très long.

Découper les conditions

Les conditions ne doivent pas dépasser une seule ligne. Drupal nous encourage à assigner la valeur d'une condition à une variable pour plus de lisibilité. Ci-dessous un exemple de comment retravailler les lignes de conditions trop longues.

Mauvais :

  if ((isset($key) && !empty($user->uid) && $key == $user->uid) || (isset($user->cache) ? $user->cache : '') == ip_address() || isset($value) && $value >= time())) {
    ...
  }

Correct :

$is_valid_user = isset($key) && !empty($user->uid) && $key == $user->uid;

  // L'IP doit correspondre au cache pour éviter le détournement de session.
  $is_valid_cache = isset($user->cache) ? $user->cache == ip_address() : FALSE;

  // Alternativement, si le paramètre de requête est dans le futur, alors il
  // est toujours valide, car la galaxie implosera et s'effondrera de toute façon.
  $is_valid_query = $is_valid_cache || (isset($value) && $value >= time());

  if ($is_valid_user || $is_valid_query) {
    ...
  }

Exemple de fonction

function funstuff_system($field) {
  $system["description"] = t("This module inserts funny text into posts randomly.");
  return $system[$field];
}

Les arguments avec des valeurs par défaut doivent toujours être en fin de liste. Les fonctions anonymes, en revanche, doivent avoir un espace entre le mot "function" et ses paramètres, comme dans l'exemple suivant :

array_map(function ($item) use ($id) {
  return $item[$id];
}, $items);

Normes de codage JavaScript pour Drupal

Ajoutez toujours vos scripts JS en utilisant Drupal.behavior. Les noms de fonction doivent commencer par le nom du module ou du thème qui déclare la fonction afin d'éviter les collisions de noms.

Drupal.behaviors.tableDrag = function (context) {
  Object.keys(Drupal.settings.tableDrag).forEach(function (base) {
    $('#'+ base).once('tabledrag', addBehavior);
  });
};

Normes de codage CSS pour Drupal

Ci-dessous, quelques règles pour vous aider à coder correctement en CSS.

Évitez de compter sur la structure HTML

Le CSS doit définir l'apparence d'un élément quel que soit l'endroit et où il apparaît. Ne jamais utiliser les secteurs HTML.

BEM

Une bonne pratique lors de l'écriture de styles dans Drupal est de suivre la méthodologie BEM. Écrire du code CSS de cette façon empêche les imbrications multiples et la dépendance à la structure du markup ainsi qu'à des noms de classes trop génériques. La méthodologie divise tous les éléments en trois catégories :

Blocs – il s'agit généralement de composants uniques, par exemple, une navigation. Cela ressemble à une seule classe dans le code, par exemple .navigation.
Éléments – c'est-à-dire les parties subordonnées d'un bloc, comme un lien dans la navigation. Le nom de l'élément doit être séparé du nom du bloc par deux underscores, par exemple .navigation__link, .navigation__item.
Modificateurs – variantes spécifiques de blocs et d'éléments. Le nom du modificateur doit être séparé de la base par deux tirets, par exemple : .navigation–dark, .navigation__link–active.

Normes de codage Twig pour Drupal

Toutes les normes de codage pour Twig, le moteur de templates pour PHP, sont décrites sur la page de la documentation officielle de Twig.

Expressions

Les expressions dans Twig sont très similaires aux expressions en PHP. Elles sont principalement utilisées pour vérifier si une variable existe, déclarer des boucles et de nouvelles variables dans les templates.

Vérifier si une variable est disponible pour l'impression :

{% if foo %}
  {{ foo }}
{% endif %}

Boucle :

{% for key, value in items %}
  {{ value }}
{% endfor %}

Déclaration de nouvelles variables :

{% set list = ['Alice', 'Bob'] %}
{% set text = ':person is a Twig fan'|t({':person': list[0] }) %}

Filtres

Certaines des fonctionnalités les plus populaires de Drupal, telles que t et url, ont été rendues disponibles en tant que filtres dans les templates Twig. Elles sont déclenchées par le caractère pipe | .


  {{ 'Original'|t }}

Comment utiliser les normes de codage Drupal au quotidien ?

Il existe des outils disponibles pour vous aider à formater votre code afin qu'il soit conforme aux normes. Voici quelques-uns des outils que nous utilisons pendant le développement Drupal.

Code Sniffer – un outil pour vous aider à écrire du code pour Drupal ou ses modules. Il est capable de détecter et de corriger automatiquement les erreurs de codage et de formatage standard.
Module Coder pour Drupal – lorsqu'il est intégré avec Code Sniffer, il aide à corriger les bogues dans la norme de codage.
CSSComb - un outil pour trier et formater le code CSS.

Lors de l'utilisation d'outils intégrés à l'IDE, le développeur n'a pas besoin de connaître toutes les normes de codage par cœur et peut être sûr qu'il n'y aura pas d'espaces inutiles ou de tabulations incorrectes dans le code. Ils découvriront également si des changements sont introduits dans la convention de codage.

En conclusion, il est très important que l'équipe de développement adhère aux conventions et normes de codage appropriées qui la guideront pendant le développement logiciel. Cela aidera à maintenir la qualité du code et à réduire le temps que les nouveaux développeurs passent à essayer de comprendre une base de code complexe.