Projet

Général

Profil

Historique

Auparavant les scripts n'étaient pas rédigés suivant une convention commune à chacun. Ce qui fait que l'entretien de ces derniers pouvait se révéler compliqué. Le but de cette convention est d'harmoniser l'écriture des scripts afin de les rendre plus lisibles, et plus faciles à entretenir.

Nommage

Pour les noms de scripts :

  • Nom du script en anglais
  • Mettre des - à la place des _ car les scripts du dossier scripts de Drupal sont nommés comme ça.

  • Mettre l'extension à la fin (exemple : .sh)

  • Pour avoir la coloration syntaxique automatique

  • Drupal se base sur les extensions pour poster les fichiers. Et s’il n’y en a pas, il refusera de le poster.

  • Cela permet de se rappeler que l'on utilise un script

  • Faire des noms parlant et descriptif (quitte à ce qu'il soit long), exemple :

  • maj_d7.sh -> update-all-d7-contributed-modules.sh ou update-contributed-modules-all-d7.sh

  • captcha.sh -> force-all-d7-captcha-activation.sh ou force-captcha-activation-all-d7.sh

Des noms de scripts avec des diminutifs de noms ou des acronymes peuvent être utilisés mais ils doivent être documentés et il faut en informer l'équipe, exemple :

  • d7 : pour la version Drupal cible du module
  • all : pour tous les sites d'une version, si non précisé sous-entend que le script n'affecte qu'un site

Ces diminutifs et acronymes doivent être mis de préférence en début de nom, une exception peut être faite si le diminutif s'insére bien dans le nom du script, exemple d'un script de Drupal : generate-d7-content.sh

Ordre des diminutifs

Les diminutifs doivent être placés dans l'ordre suivant :

  • Version de Drupal : dx
  • Affecte tous les sites ou non : all
  • Autre ...

Renommage d'un script

En cas de renommage d'un script, il faut vérifier :

  • Les dépendances de scripts entre eux (voir le fichier les listant)
  • Le crontab

Rédaction

  • Une ligne = une action, si une ligne fait plus qu'une action cela devient dur à lire. Si la ligne a vraiment besoin de faire plus qu'une action, mettre un commentaire avant.
  • Ne pas répéter le code, ou alors un minimum.
  • Mettre toutes les variables/fonctions communes à plusieurs scripts dans des fichiers à part qu’on importe

Les commentaires

  • Les commentaires sont en anglais (langage des programmeurs et pas de problème d'accents selon l'éditeur utilisé).
  • Ne pas coller les commentaires au symbole de commentaire, exemple à suivre : # Comment.

Les variables

  • Les variables sont en anglais (langage des programmeurs et pas de problème d'accents selon l'éditeur utilisé).
  • Emploi des underscores pour séparer les mots dans le nom de la variable
  • Ne pas avoir peur de donner des noms longs aux variables (d'autant que les éditeurs digne de ce nom dispose de l'autocomplétion), il faut que le lecteur sache spontanément en lisant le nom de la variable, son type et son utilité, exemple :
    • madate -> my_date -> current_date (si fait pour utiliser la date actuelle)
  • Les variables doivent doivent toujours être entre guillements doubles (ie "$var"). Cela évite des éventuels problème de gestion des espaces, par exemple cd $dir peut poser problème si dir="Ping Pong" tandis que cd "$dir" est correct.
  • Les variables (hors paramètres positionnels) s'utilisent entre accolades, eg ${ma_var}. Améliore la lisibilité.

Les commandes

  • Les substitutions de commande s'écrivent avec la syntaxe $(…) et sont entre guillemets, eg "$(ls)". Même raison que précédemment. De plus, la syntaxe $(…) permet d'empiler des commandes, eg $(ls $(ls ~)) ou mieux : "$(ls "$(ls)")" (les guillements n'ont pas besoin d'être échappés car ce qui est entre $(…) est parsé comme si c'était sur une ligne de l'interpréteur)

Les imports

Les imports se font en début de script, avant le commentaire de description de site.

Les fonctions de contrôle

Les fonctions de contrôle se placent après le commentaire de description de site.

Options

Afin de faciliter l'utilisation des scripts, il est recommandé d'importer source:bin/print-help-if-required.sh après avoir défini une fonction usage. Voir source:bin/d7-all-update-core.sh pour un exemple. Il est également conseillé d'utiliser getopts et d'utiliser les paramètres de scripts, tant pour faciliter l'affichage de l'aide que de faciliter l'utilisation. Voir source:bin/flush-files.sh pour un exemple.

Ne pas faire

Ne pas : mettre son nom, la date et le commentaire qui dit ce que fait le script dans le script car

  • La date laisse penser que le script est parfois vieux
  • Comme on a pas envie de modifier cet en-tête, le commentaire d'explication de ce que fait le script n'est pas mis à jour
  • Ça donne l'impression que le script appartient à cette personne et ne donne pas envie de le modifier (on peut s'imaginer que c'est le script de la personne et que donc c'est à elle à l'entretenir)
  • Le nom du script doit de lui-même indiqué ce que le script fait
  • Pour la date et les modification, il y a git
  • Pour la reconnaissance du travail des personnes -> type de contenus "membre" sur default et/ou s'il le faut une page dédiée aux contributions de chacun sur default

Plus généralement

Plus généralement, suivre le clean code :