Commentaire JavaScript

Un commentaire JavaScript est ignoré par le moteur du navigateur. Il sert à expliquer une intention que le code ne dit pas, ou à neutraliser un bloc le temps d’un test. Ce qu’il ne fait pas : disparaître du fichier envoyé au visiteur.

Les deux syntaxes du commentaire JavaScript

Le commentaire de ligne commence par // et court jusqu’à la fin de la ligne.

// Recalcule le total avant l'envoi du formulaire
const total = calculerTotal(panier);

Le commentaire de bloc s’ouvre avec /* et se ferme avec */, sur autant de lignes que nécessaire.

/*
  Le tri se fait côté client tant que
  la liste reste courte.
*/

Un commentaire se place avant, après ou au milieu d’une instruction. La convention qui tient dans une équipe est simple : le commentaire de ligne au-dessus de ce qu’il décrit, le commentaire de bloc réservé aux en-têtes de fichier et à la documentation.

Neutraliser du code sans le supprimer

C’est l’usage le plus courant : mettre un bloc en commentaire pour vérifier qu’il est bien la cause d’un comportement. Le raccourci Ctrl + / sur Windows et Linux, Cmd + / sur Mac, commente et décommente la sélection dans Visual Studio Code comme dans PhpStorm.

Ce réflexe a une limite. Du code commenté qui reste en place plusieurs mois devient du code mort : personne ne sait plus s’il attend d’être réactivé ou s’il a été abandonné. L’historique Git tient ce rôle mieux qu’un commentaire. Supprimer le bloc et le retrouver dans un commit est plus sûr que le laisser dormir dans le fichier.

Le piège du commentaire de bloc

Les commentaires de bloc ne s’imbriquent pas. Le premier */ rencontré ferme le commentaire, quel que soit le nombre de /* ouverts avant lui. Commenter une portion de code qui contient déjà un commentaire de bloc laisse donc du code actif derrière la fermeture.

/*
  /* ancien calcul */
  const x = 1;
*/

Ici le commentaire se ferme dès la deuxième ligne. La déclaration de x reste active et le dernier */ provoque une erreur de syntaxe. Même effet avec une séquence */ qui apparaît dans une chaîne de caractères ou dans une expression régulière à l’intérieur du bloc commenté.

Pour neutraliser plusieurs lignes sans surprise, le commentaire de ligne appliqué à chaque ligne est plus fiable. C’est exactement ce que fait le raccourci de l’éditeur.

JSDoc, le commentaire qui documente

Un commentaire de bloc ouvert par /** est interprété par les éditeurs et par les outils de documentation. Les types annotés remontent dans l’autocomplétion, sans avoir à passer le projet à TypeScript.

/**
 * Applique une remise à un montant.
 * @param {number} montant - Montant hors taxes.
 * @param {number} taux - Taux de remise entre 0 et 1.
 * @returns {number} Montant remisé.
 */
function appliquerRemise(montant, taux) {}

Sur un projet repris à un autre prestataire, c’est le premier investissement rentable : documenter les fonctions d’entrée d’un module avant d’y toucher.

Ce que deviennent les commentaires en production

Un fichier JavaScript est servi tel quel au navigateur. Les commentaires y sont lisibles par n’importe qui, exactement comme le commentaire HTML. La minification les retire du fichier livré sans toucher aux sources, et c’est l’une des optimisations appliquées lors d’un travail sur la vitesse de chargement.

Deux réserves. La minification ne traite que les fichiers qu’on lui donne : un script inséré directement dans le HTML par une extension y échappe souvent. Et les source maps, quand elles sont publiées sur le serveur, republient le code d’origine avec ses commentaires. Un jeton d’API laissé en commentaire ressort alors intact.

Une convention d’équipe plutôt qu’un réflexe

Le bon commentaire explique pourquoi, pas quoi. Un // incrémente i ne sert à rien, la ligne le dit déjà. Un // l’API renvoie les dates en UTC, on décale ici évite la prochaine régression. Sur les projets que nos équipes de développement web reprennent, ce sont ces commentaires qui font gagner des jours.