Projet

Général

Profil

Convention redaction de script » Historique » Version 7

Florent Torregrosa, 31/07/2013 12:49
diminutifs en début de nom + Ordre des diminutifs

1 1 Florent Torregrosa
h1. Convention rédaction de script
2 1 Florent Torregrosa
3 5 Florent Torregrosa
{{>toc}}
4 5 Florent Torregrosa
5 4 Julien Enselme
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.
6 1 Florent Torregrosa
7 1 Florent Torregrosa
h2. Nommage
8 1 Florent Torregrosa
9 1 Florent Torregrosa
Pour les noms de scripts :
10 3 Julien Enselme
11 4 Julien Enselme
* Nom du script en anglais
12 4 Julien Enselme
* Mettre des @-@ à la place des @_@ car les scripts du dossier scripts de Drupal sont nommés comme ça.
13 4 Julien Enselme
* Mettre l'extension à la fin (exemple : .sh)
14 3 Julien Enselme
15 4 Julien Enselme
 * Pour avoir la coloration syntaxique automatique
16 1 Florent Torregrosa
 * Drupal se base sur les extensions pour poster les fichiers. Et s’il n’y en a pas, il refusera de le poster.
17 4 Julien Enselme
 * Cela permet de se rappeler que l'on utilise un script
18 1 Florent Torregrosa
19 4 Julien Enselme
* Faire des noms parlant et descriptif (quitte à ce qu'il soit long), exemple :
20 2 Julien Enselme
21 3 Julien Enselme
 * maj_d7.sh -> update-all-d7-contributed-modules.sh ou update-contributed-modules-all-d7.sh
22 2 Julien Enselme
 * captcha.sh -> force-all-d7-captcha-activation.sh ou force-captcha-activation-all-d7.sh
23 2 Julien Enselme
24 1 Florent Torregrosa
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 :
25 4 Julien Enselme
26 1 Florent Torregrosa
* d7 : pour la version Drupal cible du module
27 7 Florent Torregrosa
* all : pour tous les sites d'une version, si non précisé sous-entend que le script n'affecte qu'un site
28 1 Florent Torregrosa
29 7 Florent Torregrosa
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
30 7 Florent Torregrosa
31 7 Florent Torregrosa
h2. Ordre des diminutifs
32 7 Florent Torregrosa
33 7 Florent Torregrosa
Les diminutifs doivent être placés dans l'ordre suivant :
34 7 Florent Torregrosa
35 7 Florent Torregrosa
* Version de Drupal : dx
36 7 Florent Torregrosa
* Affecte tous les sites ou non : all
37 7 Florent Torregrosa
* Autre ...
38 1 Florent Torregrosa
39 1 Florent Torregrosa
h3. Renommage d'un script
40 1 Florent Torregrosa
41 1 Florent Torregrosa
En cas de renommage d'un script, il faut vérifier :
42 4 Julien Enselme
* Les dépendances de scripts entre eux (voir le fichier les listant)
43 4 Julien Enselme
* Le crontab
44 1 Florent Torregrosa
45 1 Florent Torregrosa
h2. Rédaction
46 1 Florent Torregrosa
47 4 Julien Enselme
* 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.
48 4 Julien Enselme
* Ne pas répéter le code, ou alors un minimum.
49 4 Julien Enselme
* Mettre toutes les variables/fonctions communes à plusieurs scripts dans des fichiers à part qu’on importe
50 1 Florent Torregrosa
51 1 Florent Torregrosa
h3. Les commentaires
52 1 Florent Torregrosa
53 1 Florent Torregrosa
* Les commentaires sont en anglais (langage des programmeurs et pas de problème d'accents selon l'éditeur utilisé).
54 6 Florent Torregrosa
* Ne pas coller les commentaires au symbole de commentaire, exemple à suivre : # Commentaire.
55 1 Florent Torregrosa
56 1 Florent Torregrosa
h3. Les variables
57 1 Florent Torregrosa
58 4 Julien Enselme
* Les variables sont en anglais (langage des programmeurs et pas de problème d'accents selon l'éditeur utilisé).
59 4 Julien Enselme
* Emploi des underscores
60 4 Julien Enselme
* 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 :
61 1 Florent Torregrosa
62 1 Florent Torregrosa
 * madate -> my_date -> current_date (si fait pour utiliser la date actuelle)
63 1 Florent Torregrosa
64 4 Julien Enselme
* Les variables de chemin doivent être placées en début de script (plus tard factorisation)
65 1 Florent Torregrosa
66 3 Julien Enselme
h3. Ne pas faire
67 1 Florent Torregrosa
68 4 Julien Enselme
Ne pas : mettre son nom, la date et le commentaire qui dit ce que fait le script dans le script car
69 1 Florent Torregrosa
70 4 Julien Enselme
* La date laisse penser que le script est parfois vieux
71 4 Julien Enselme
* 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
72 4 Julien Enselme
* Ç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)
73 4 Julien Enselme
* Le nom du script doit de lui-même indiqué ce que le script fait
74 4 Julien Enselme
* Pour la date et les modification, il y a git
75 4 Julien Enselme
* 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
76 4 Julien Enselme
77 1 Florent Torregrosa
h2. Plus généralement
78 1 Florent Torregrosa
79 4 Julien Enselme
Plus généralement, suivre le clean code :
80 4 Julien Enselme
81 4 Julien Enselme
* En anglais : http://www.e-reading-lib.com/bookreader.php/134601/Clean_Code_-_A_Handbook_of_Agile_Software_Craftsmanship.pdf