Commentaires JavaScript

Introduction

Ce chapitre couvre tout ce dont vous avez besoin pour écrire de bons commentaires JavaScript : les deux syntaxes de commentaires (// pour les commentaires de ligne et /* */ pour les commentaires de bloc), les doc-commentaires JSDoc pour documenter les fonctions, la différence entre les commentaires utiles et nuisibles, et comment désactiver du code pendant le débogage. Les commentaires sont du texte que le moteur JavaScript ignore entièrement lors de l'exécution — ils existent uniquement pour les humains. Ils expliquent votre code à quiconque le lit plus tard, y compris vous-même dans le futur et vos coéquipiers. Comme ils sont exclus de l'exécution, les commentaires n'ont aucun coût à l'exécution. (Une directive associée qui est lue par le moteur est "use strict" ; malgré son apparence de chaîne en haut d'un fichier, elle modifie le comportement du code — voir le chapitre sur le mode strict.)

Pourquoi les commentaires sont essentiels en JavaScript

Les commentaires peuvent sembler secondaires, mais ils jouent un rôle central dans le développement. Ils aident à :

• Documentation du code : Pour expliquer une logique complexe ou le raisonnement derrière certains segments de code.
• Lisibilité du code : Améliorer la compréhension du flux et de la fonctionnalité du code.
• Débogage : Activer ou désactiver facilement des parties du code pendant les tests ou le débogage.
• Collaboration en équipe : Aider les autres développeurs à comprendre votre processus de réflexion.

Types de commentaires JavaScript

JavaScript prend en charge deux types principaux de commentaires :

Commentaires sur une ligne

Les commentaires sur une ligne commencent par // et s'étendent jusqu'à la fin de la ligne courante. Tout ce qui suit // sur cette ligne est ignoré. Ils peuvent se trouver sur leur propre ligne ou à la fin d'une ligne de code (un commentaire en ligne) :

// This whole line is a comment
let a = 5, b = 10;

let sum = a + b; // inline comment: add the two values

Comme un commentaire // ne s'étend que jusqu'à la fin de la ligne, la ligne suivante reprend le code normal — vous n'avez pas besoin de le « fermer ».

Commentaires multi-lignes

Les commentaires multi-lignes (aussi appelés commentaires de bloc) commencent par /* et se terminent par */. Tout ce qui se trouve entre les deux est ignoré, même sur plusieurs lignes. Utilisez-les pour des explications plus longues :

/*
  Returns the sum of two numbers.
  Both arguments are expected to be numbers;
  passing strings will concatenate instead of add.
*/
function add(a, b) {
    return a + b;
}

Vous pouvez également utiliser la syntaxe de bloc au milieu d'une ligne, par exemple pour étiqueter un argument : setTimeout(run, 1000 /* ms */).

Attention — les commentaires de bloc ne s'imbriquent pas. Un */ termine le commentaire à la première occurrence, donc encadrer du code qui contient déjà /* ... */ dans un autre commentaire de bloc pose problème. Le */ intérieur ferme le commentaire prématurément et le reste devient du code actif :

/*
  /* inner */
  alert('this still runs!');
*/

Copier

Pour commenter une région qui contient des commentaires de bloc, utilisez plutôt // sur chaque ligne.

Bons vs. mauvais commentaires : expliquez le pourquoi, pas le quoi

La règle la plus utile : commentez le pourquoi, pas le quoi. Le code dit déjà ce qu'il fait ; un bon commentaire capture l'intention, le compromis ou la contrainte surprenante que le code ne peut pas exprimer par lui-même.

// Bad: just restates the code — adds noise, can go stale
let total = 0; // set total to 0

// Good: explains a non-obvious constraint
const RETRY_LIMIT = 3; // the payment API rejects bursts above 3 calls/sec

Préférez un code auto-documenté aux commentaires quand c'est possible. Un nom de variable bien choisi ou une petite fonction suffit souvent à éviter tout commentaire :

// Needs a comment because the intent is hidden:
if (u.a && Date.now() - u.l < 86400000) { /* active in last 24h */ }

// No comment needed — the names say it:
const isActive = user.isVerified && wasSeenInLast24Hours(user);
if (isActive) {
  // ...
}

Quelques autres règles :

1. Maintenez-les à jour. Un commentaire qui contredit le code est pire qu'aucun commentaire — les lecteurs ne savent plus lequel croire.
2. Soyez concis. Expliquez le raisonnement, pas chaque étape.
3. Ne commentez pas du code mort de façon permanente. Supprimez-le ; le contrôle de version s'en souvient.

Désactiver du code via des commentaires

Pendant le débogage, vous souhaitez souvent désactiver une ligne ou un bloc sans le supprimer. Préfixez une ligne avec //, ou encadrez une région avec /* */ :

let value = compute();
// console.log('Debug:', value); // temporarily silenced

/*
expensiveLogging(value);
sendToAnalytics(value);
*/

C'est très utile pour isoler quelle partie du code cause un problème. De nombreux éditeurs basculent cela avec un raccourci clavier. Voir le chapitre Console API pour des alternatives plus propres aux console.log de débogage oubliés.

Marqueurs TODO et FIXME

Une convention courante consiste à baliser le travail inachevé avec TODO (quelque chose à faire plus tard) ou FIXME (un bug connu). Les éditeurs et les linters peuvent en faire la liste pour vous :

// TODO: optimize this loop for large data sets
// FIXME: breaks when input is an empty array

JSDoc : documenter les fonctions

JSDoc est un standard pour documenter les fonctions à l'aide d'un commentaire de bloc spécial qui s'ouvre avec /** (deux astérisques). Des balises telles que @param et @returns décrivent les entrées et la sortie. Les outils et les éditeurs lisent ces informations pour afficher des suggestions en ligne et générer de la documentation HTML.

/**
 * Adds two numbers together.
 * @param {number} a - The first addend.
 * @param {number} b - The second addend.
 * @returns {number} The sum of a and b.
 */
function add(a, b) {
    return a + b;
}

console.log(add(2, 3)); // 5

JSDoc s'associe particulièrement bien aux fonctions : documenter les paramètres et les types de retour rend le contrat d'une fonction clair sans avoir à lire son corps. Parmi les autres balises courantes figurent @throws, @example et @deprecated.

Conclusion

Intégrer des commentaires efficaces en JavaScript n'est pas seulement une pratique de codage, mais une compétence de communication. Cela contribue considérablement à la maintenabilité et à l'évolutivité du code. En maîtrisant les commentaires JavaScript, vous améliorez non seulement votre code, mais aussi votre collaboration avec les autres dans le processus de développement.

Souvenez-vous qu'un code bien commenté est le reflet d'un développeur réfléchi et professionnel. Exploitez la puissance des commentaires et regardez votre code JavaScript se transformer en un actif plus accessible et plus maintenable.

Pratique