Convention redaction de script » Historique » Version 7
Version 6 (Florent Torregrosa, 31/07/2013 09:00) → Version 7/16 (Florent Torregrosa, 31/07/2013 12:49)
h1. Convention rédaction de script
{{>toc}}
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.
h2. 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
* d7 : pour la version Drupal cible du module
Ces diminutifs et acronymes doivent être mis de préférence en début (début/fin ?) de nom, une exception peut être faite sauf si le diminutif s'insére bien dans le nom du script, exemple d'un script de Drupal : generate-d7-content.sh
h2. 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 ...
h3. 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
h2. 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
h3. 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 : # Commentaire.
h3. Les variables
* Les variables sont en anglais (langage des programmeurs et pas de problème d'accents selon l'éditeur utilisé).
* Emploi des underscores
* Ne pas avoir peur de donner des noms longs aux variables, 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 de chemin doivent être placées en début de script (plus tard factorisation)
h3. 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
h2. Plus généralement
Plus généralement, suivre le clean code :
* En anglais : http://www.e-reading-lib.com/bookreader.php/134601/Clean_Code_-_A_Handbook_of_Agile_Software_Craftsmanship.pdf
{{>toc}}
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.
h2. 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
* d7 : pour la version Drupal cible du module
Ces diminutifs et acronymes doivent être mis de préférence en début (début/fin ?) de nom, une exception peut être faite sauf si le diminutif s'insére bien dans le nom du script, exemple d'un script de Drupal : generate-d7-content.sh
h2. 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 ...
h3. 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
h2. 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
h3. 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 : # Commentaire.
h3. Les variables
* Les variables sont en anglais (langage des programmeurs et pas de problème d'accents selon l'éditeur utilisé).
* Emploi des underscores
* Ne pas avoir peur de donner des noms longs aux variables, 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 de chemin doivent être placées en début de script (plus tard factorisation)
h3. 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
h2. Plus généralement
Plus généralement, suivre le clean code :
* En anglais : http://www.e-reading-lib.com/bookreader.php/134601/Clean_Code_-_A_Handbook_of_Agile_Software_Craftsmanship.pdf