Documenter une base FileMaker (5)

Commenter ses scripts

Depuis quelques temps déjà, nous vous invitons à « documenter » vos bases, c’est-à-dire à laisser des « indices » suffisamment clairs et précis un peu partout dans votre base pour que vous ou un autre développeur puisse la reprendre et la poursuivre, en comprenant aisément ce qui a été fait et pensé auparavant.

Depuis déjà de nombreuses versions, il est possible d’inclure dans vos scripts des commentaires, et ceci est particulièrement précieux en ce lieu « stratégique » que sont les scripts…

Si vos scripts ne possèdent que deux ou trois lignes d’actions, un commentaire ne s’impose pas. S’il en possède un grand nombre, ceci devient incontournable, ne serait-ce que pour repérer et comprendre rapidement à quoi correspondent vos différents « groupes d’actions »…

Tiens, à propos, comme il y a des « groupements d’occurrences de tables », ne pourrait-on pas parler de « groupes d’actions de script » ou « GAS » ? C’est peut-être le moment d’innover dans le langage filemakeurien 😉

Quels commentaires laisser dans un script ?

Avant de s’interroger sur comment, dans les faits, commenter un script, je vous invite d’abord à vous poser la question : en vue de quoi poser un commentaire ?

On l’a compris, il s’agit de laisser une information utile au développeur qui prendra la suite de la réalisation de l’app, que ce développeur soit votre collègue, votre successeur ou… vous-même 😉

De quelles types d’informations a-t-il besoin ?

J’en ai pour ma part repérer trois.

1) Il a besoin d’abord d’informations d’ordre général. Cela est particulièrement importante dans le cadre d’un travail collaboratif, même si ce n’est pas non plus à négliger lorsqu’on travaille seul. Il s’agit d’identifier le script avec trois informations :

• le nom ou les initiales du développeur – connaître l’identité du créateur du script
• la date de création du script
• son objectif (ce qu’il est censé faire) si le titre du script ne suffit pas à l’évoquer suffisamment précisément…

On place ces informations en tout début du script, avant toute action.

Si le script est appelé à être modifié par la suite, le nom ou les initiales du modificateur (si différents du créateur du script) peuvent être ajoutés, avec la date et les indications des modifications apportées.

2) Dans mon article précédent, vous étiez invité à classer vos scripts. Ici, à l’intérieur de chaque script, il s’agit non de classer les actions de script, puisqu’elles ont leur ordre logique, mais de donner des repères, c’est-à-dire d’indiquer les différentes étapes du processus engagé par le script.

Ces informations ponctuent donc tout le script…

3) On peut également, à l’aide d’un commentaire, donner une explication complémentaire. Par exemple, indiquer que le paramètre de script récupéré correspond à tel bouton placé à tel endroit sur tel modèle ; signaler que dans le calcul de la condition Si – Fin de si, on utilise une fonction personnalisée ; noter une option non directement visible lorsque le script est affiché avec ses différentes lignes d’actions, pour éviter d’avoir à cliquer sur la ligne concernée pour voir quelle option a été définie…

Notre premier écran ci-dessus en donnait un exemple simple : le commentaire placé au-dessus de l’action Exécuter la recherche indique le critère de recherche et de tri du résultat pour cette requête…

Comment insérer ces commentaires dans les scripts ?

La ou les lignes permettant de noter des commentaires dans un script s’utilise et s’insère dans le script exactement comme n’importe quelle action de script. On trouve cette « action » de script dans la liste des actions de script, dans la catégorie Divers.

Notez cependant que j’ai mis « action » de script entre guillemets.

En effet, nous n’avons pas ici affaire à une action de script.
Lorsque FileMaker parcourt la liste des actions de votre script, il saute toutes les lignes commençant par un #, c’est-à-dire toutes celles correspondant à un commentaire… En effet, ils ne lui sont pas destinés. FileMaker, grâce à ce que vous avez construit dans votre script, sait ce qu’il a à faire et n’a pas besoin d’explications complémentaires. Elles sont donc destinées à des humains, et non à FileMaker 😉

Mais au fait, est-ce que le fait de poser des commentaires dans les scripts ralentit leur effectuation ?

Non !

Que ce soit dans un calcul, une rubrique, dans le graphe des liens ou dans les scripts, les commentaires que vous y insérer n’ont aucune incidence sur la performance de FileMaker. Vous pouvez en poser autant que vous voulez, autant que nécessaire, sans aucun scrupule.

Une interface remaniée depuis FileMaker 14

Comme je vous le rappelais dans mon précédent article, FileMaker 14 a opéré une véritable petite révolution dans l’interface de création et de modification des scripts.

Dans les versions antérieures à FileMaker 14, notre ligne de script Commentaire était précédée d’un dièse, # et l’ensemble de la ligne (avec le contenu que vous avez saisi) en gras. Comme sur l’ensemble du script, pas de couleur, mais le gras des lignes de commentaire permettait de les mettre en valeur.

Pour saisir un nouveau commentaire, pas d’autre solution que d’activer l’action Commentaire, de double-cliquer dessus pour qu’elle se positionne dans votre script là où se trouve votre curseur. Vous pouvez ensuite saisir votre commentaire.

Depuis FileMaker 15, on peut toujours procéder ainsi, mais en plus, on peut, à l’intérieur du script, faire un simple « retour chariot » (création d’une ligne blanche), saisir « co » par exemple et choisir dans la liste proposée #(commentaire).  Gain de temps appréciable 😉

En outre, l’interface s’est colorée puisque désormais, vous pouvez attribuer une couleur à chaque type de ligne d’action. Les commentaires par défaut sont en vert.

Notez en outre, comme le montre l’écran ci-dessus, que pour créer une ligne blanche dans votre script et l’aérer – en créant ainsi des « GAS » (Groupes d’actions de script – ouf, j’ai réussi à placer mon néologisme une deuxième fois dans mon article 😉 ), vous devez créer une nouvelle ligne de commentaire, précédée d’un # mais dans laquelle vous ne saisissez rien. Depuis FileMaker Pro 14, il suffit pour cela de faire un banal retour chariot pour qu’une ligne blanche apparaisse…

Alors, maintenant que vous savez comment commenter vos scripts, à vous de jouer 😉

Marie-Charlotte Potton

Premier article / Article précédent / Article suivant

Tags: Documenter, FileMaker 14, scripts