Convention redaction de script » Historique » Version 4
Version 3 (Julien Enselme, 27/07/2013 16:49) → Version 4/16 (Julien Enselme, 27/07/2013 19:48)
h1. Convention rédaction de script
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 facile à entretenir.
h2. Nommage
Pour les noms de scripts :
* Nom nom du script en anglais
* Mettre mettre des @-@ à la place des @_@ car les scripts du dossier scripts de Drupal sont nommés comme ça.
* Mettre mettre l'extension à la fin (exemple : .sh)
* Pour 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 cela permet de se rappeler que l'on utilise un script
* Faire 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 :
* 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 en (début/fin ?) de nom, sauf si
h3. Renommage d'un script
En cas de renommage d'un script, il faut vérifier :
* Les les dépendances de scripts entre eux eux. (voir le fichier les listant)
* Le le crontab
h2. Rédaction
* Une 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 ne pas répéter le code, ou alors un minimum.
* Mettre 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 d'accent selon l'éditeur utilisé).
h3. Les variables
* Les les variables sont en anglais (langage des programmeurs et pas de problème d'accents d'accent selon l'éditeur utilisé).
* Emploi emploi des underscores
* Ne 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 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 la date laisse penser que le script est parfois vieux
* Comme comme on a pas envie de modifier cet en-tête, résultat le commentaire d'explication de ce que fait le script n'est pas mis à jour
* Ça ç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 le nom du script doit de lui-même indiqué ce que le script fait
* Pour pour la date et les modification, il y a git
* Pour 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
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 facile à entretenir.
h2. Nommage
Pour les noms de scripts :
* Nom nom du script en anglais
* Mettre mettre des @-@ à la place des @_@ car les scripts du dossier scripts de Drupal sont nommés comme ça.
* Mettre mettre l'extension à la fin (exemple : .sh)
* Pour 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 cela permet de se rappeler que l'on utilise un script
* Faire 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 :
* 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 en (début/fin ?) de nom, sauf si
h3. Renommage d'un script
En cas de renommage d'un script, il faut vérifier :
* Les les dépendances de scripts entre eux eux. (voir le fichier les listant)
* Le le crontab
h2. Rédaction
* Une 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 ne pas répéter le code, ou alors un minimum.
* Mettre 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 d'accent selon l'éditeur utilisé).
h3. Les variables
* Les les variables sont en anglais (langage des programmeurs et pas de problème d'accents d'accent selon l'éditeur utilisé).
* Emploi emploi des underscores
* Ne 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 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 la date laisse penser que le script est parfois vieux
* Comme comme on a pas envie de modifier cet en-tête, résultat le commentaire d'explication de ce que fait le script n'est pas mis à jour
* Ça ç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 le nom du script doit de lui-même indiqué ce que le script fait
* Pour pour la date et les modification, il y a git
* Pour 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