Editions ENI Livres | Vidéos | e-Formations
Documenter et déboguer son code Apps Script
Introduction
Documenter et déboguer son code font partie intégrante du travail du développeur.
La documentation assure la lisibilité et la pérennité du projet, tandis que le débogage garantit son bon fonctionnement.
Documenter son code
Je construis toujours un projet en pensant à la personne qui devra, un jour, reprendre le code, et je veux lui faciliter la tâche. Parfois, cette personne… c’est moi : revenir sur un ancien morceau de code sans explications, c’est oublier pourquoi tel choix a été fait.
La documentation devient alors un allié indispensable, à la fois pour transmettre clairement l’intention et pour accélérer toute maintenance ou évolution.
1. JSDoc : conventions utiles dans Apps Script
Au-delà des commentaires « in-line » qui expliquent la logique au sein d’une fonction, par exemple :
// Resume from last processed index (0-based in 'data')
let i = Math.max(0, parseInt(scriptProperties.getProperty('JOB__LAST_ROW') || '0', 10)); Pour mettre en commentaire plusieurs lignes, on peut les sélectionner et utiliser le raccourci [Ctrl] [/].
Il est particulièrement utile, avec Apps Script, d’adopter JSDoc.
JSDoc est une syntaxe de commentaire destinée à documenter du code JavaScript. On y décrit les paramètres, les valeurs de retour et la forme des objets, grâce à des balises mises à disposition.
Les balises les plus populaires sont les suivantes :
-
@author, nom ou pseudo du développeur
-
@constructor, marque...
Déboguer efficacement
Le débogage dans Apps Script repose sur deux leviers complémentaires : l’inspection pas-à-pas avec le débogueur intégré et la lecture des journaux d’exécution.
1. Utiliser le débogueur intégré
Apps Script propose un débogueur qui permet d’exécuter le code pas à pas et d’analyser l’état réel du programme.
Il est particulièrement utile lorsqu’on travaille avec des objets complexes, où les journaux ne suffisent pas toujours à comprendre le comportement du code.
Pour l’utiliser, il suffit de sélectionner la fonction à débugger, puis de cliquer sur Debug :
Pour inspecter une étape, on peut ajouter un point d’arrêt (breakpoint).
On ajoute ces points d’arrêt avec le raccourci [Ctrl] B sur la ligne concernée, ou en cliquant dans la gouttière à gauche d’une ligne :
En lançant la fonction en mode débogage, l’exécution s’interrompt à chaque point d’arrêt, ce qui permet d’observer la valeur des variables à cet instant précis et de suivre le déroulement du programme étape par étape :
Il est possible de placer des points d’arrêt même lorsque la fonction est en cours, ce qui permet d’isoler une zone problématique ou d’identifier pas à pas les bugs.
Il est également possible d’agrandir le panneau de droite pour visualiser plus facilement les variables. Par exemple, je peux facilement voir l’objet request que j’envoie à l’API Sheets, en déroulant ce dernier et en naviguant dans son contenu :
En haut du débogueur, des boutons permettent de gérer l’exécution :
-
Continue : reprend jusqu’au prochain point d’arrêt.
-
Step over : exécute la ligne courante sans entrer dans les fonctions appelées.
-
Step into : entre dans la fonction appelée sur la ligne courante.
-
Step out : termine la fonction en cours et revient à l’appelant.
S’il n’y a aucun point d’arrêt et que le script s’exécute sans erreur, le mode Debug agit exactement comme le mode Run.