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