Les commentaires JavaScript

Les commentaires JavaScript constituent un élément important de tout code source, permettant aux développeurs d’ajouter des explications, des notes ou des précisions sans affecter l’exécution du programme. Le navigateur ignore complètement ces annotations lors de l’interprétation du JavaScript, les rendant invisibles pour l’utilisateur final mais précieuses pour quiconque lit ou maintient le code.

Un commentaire sert à documenter votre intention, expliquer une logique complexe ou temporairement désactiver du code pendant les tests. Bien utilisés, les commentaires facilitent la collaboration entre développeurs et accélèrent la compréhension d’un projet. Mal utilisés, ils encombrent le code et peuvent même induire en erreur lorsqu’ils deviennent obsolètes.

JavaScript propose trois syntaxes distinctes pour commenter votre code, chacune adaptée à des situations spécifiques. Comprendre quand et comment les utiliser améliore significativement la qualité et la maintenabilité de vos projets.Apprendre à commenter correctement est aussi important qu’apprendre le langage Js.

Comment commenter en js

Les commentaires JavaScript sur une ligne

La syntaxe la plus simple utilise deux barres obliques // pour créer un commentaire qui s’étend jusqu’à la fin de la ligne. Tout ce qui suit ces deux caractères sur la même ligne devient invisible pour l’interpréteur JavaScript.

// Ceci est un commentaire sur une seule ligne
let age = 25; // On initialise l'âge à 25 ans

// La ligne suivante est désactivée
// console.log("Ce message ne s'affichera pas");

Cette syntaxe convient parfaitement aux annotations courtes qui précisent une ligne de code spécifique. Vous pouvez placer le commentaire au-dessus de l’instruction concernée ou à sa droite, selon votre préférence et les conventions de votre projet. L’avantage de cette approche réside dans sa légèreté : un coup d’œil suffit pour distinguer le code actif du texte explicatif.

Les commentaires sur une ligne servent également à désactiver temporairement du code pendant le développement. Plutôt que de supprimer une instruction que vous souhaitez conserver pour référence ou réactiver plus tard, vous la commentez simplement en ajoutant // au début. Cette technique facilite les tests et l’expérimentation sans perdre votre travail précédent.

function calculerTotal(prix, quantite) {
    // return prix * quantite; // Ancienne version simple
    return prix * quantite * 1.20; // Nouvelle version avec TVA
}

Lorsque vous devez commenter plusieurs lignes consécutives avec cette syntaxe, chaque ligne nécessite ses propres //. Cette répétition devient rapidement fastidieuse pour des blocs de texte plus longs, auquel cas la syntaxe multi-ligne s’avère plus appropriée.

Astuce : Ctrl+/ permet de commenter/décommenter instantanément.

Les commentaires JavaScript multi ligne

Pour les explications plus détaillées ou pour désactiver plusieurs lignes de code simultanément, JavaScript propose une syntaxe de commentaire multi-ligne délimitée par /* pour l’ouverture et */ pour la fermeture. Tout ce qui se trouve entre ces marqueurs devient un commentaire, quelle que soit sa longueur.

/*
Ceci est un commentaire
qui s'étend sur plusieurs lignes.
Pratique pour les explications longues.
*/

let prix = 100;

/*
function ancienneMethode() {
    // Code obsolète conservé temporairement
    console.log("Cette fonction n'est plus utilisée");
}
*/

Cette syntaxe est particulièrement utile lorsque vous devez fournir un contexte approfondi sur une fonction, expliquer un algorithme complexe ou documenter les raisons derrière une décision technique. Les explications structurées en plusieurs paragraphes restent lisibles et n’encombrent pas visuellement le code comme le feraient des dizaines de lignes commençant par //.

Les développeurs utilisent fréquemment les commentaires multi-lignes pour désactiver temporairement des blocs entiers de code pendant le débogage. Vous pouvez ainsi isoler une section problématique sans la supprimer définitivement, facilitant les tests par élimination. Une fois le problème identifié et résolu, vous supprimez simplement les marqueurs de commentaire pour réactiver le code.

function traiterCommande(commande) {
    validerCommande(commande);
    
    /*
    // Désactivation temporaire du paiement pour les tests
    if (commande.montant > 0) {
        traiterPaiement(commande);
        envoyerConfirmation(commande);
    }
    */
    
    console.log("Commande en attente");
}

Attention toutefois : les commentaires multi-lignes ne peuvent pas s’imbriquer. Si vous tentez de placer /* … */ à l’intérieur d’un autre commentaire de même type, le premier */ rencontré fermera le commentaire, causant probablement des erreurs de syntaxe pour le reste du code.

Le commentaire JSDoc

JSDoc représente une convention de documentation standardisée qui utilise la syntaxe des commentaires multi-lignes avec des annotations spécifiques commençant par @. Cette approche transforme vos commentaires en documentation structurée que des outils automatisés peuvent analyser pour générer des pages de référence complètes.

/**
 * Calcule le prix total incluant la TVA
 * @param {number} prixHT - Le prix hors taxes
 * @param {number} tauxTVA - Le taux de TVA en pourcentage (ex: 20 pour 20%)
 * @returns {number} Le prix TTC arrondi à deux décimales
 */
function calculerPrixTTC(prixHT, tauxTVA) {
    const montantTVA = prixHT * (tauxTVA / 100);
    return Math.round((prixHT + montantTVA) * 100) / 100;
}

/**
 * Représente un utilisateur du système
 * @class
 */
class Utilisateur {
    /**
     * Crée un nouvel utilisateur
     * @param {string} nom - Le nom complet de l'utilisateur
     * @param {string} email - L'adresse email valide
     */
    constructor(nom, email) {
        this.nom = nom;
        this.email = email;
    }
    
    /**
     * Envoie un email de bienvenue à l'utilisateur
     * @throws {Error} Si l'email est invalide
     * @returns {Promise<boolean>} True si l'envoi réussit
     */
    async envoyerBienvenue() {
        // Implémentation...
    }
}

La puissance de JSDoc réside dans sa capacité à documenter précisément les types de données attendus, les valeurs de retour et les exceptions possibles. Les éditeurs de code modernes comme Visual Studio Code exploitent ces informations pour offrir une auto-complétion intelligente et des avertissements lorsque vous utilisez une fonction incorrectement. Vous tapez le nom d’une fonction documentée en JSDoc, et votre éditeur affiche automatiquement la description, les paramètres attendus et le type de retour.

Les annotations JSDoc les plus courantes incluent @param pour décrire les paramètres d’une fonction, @returns pour indiquer ce qu’elle renvoie, @throws pour documenter les erreurs possibles, @class pour identifier une classe, et @type pour préciser le type d’une variable. Vous pouvez également utiliser @example pour fournir des exemples d’utilisation directement dans la documentation.

/**
 * Filtre un tableau selon un critère
 * @template T
 * @param {T[]} tableau - Le tableau à filtrer
 * @param {function(T): boolean} predicat - Fonction testant chaque élément
 * @returns {T[]} Un nouveau tableau contenant les éléments validés
 * @example
 * const nombres = [1, 2, 3, 4, 5];
 * const pairs = filtrer(nombres, n => n % 2 === 0);
 * // Résultat: [2, 4]
 */
function filtrer(tableau, predicat) {
    return tableau.filter(predicat);
}

Cette approche devient particulièrement précieuse dans les projets professionnels où plusieurs développeurs collaborent. La documentation JSDoc établit un contrat clair sur le fonctionnement de chaque fonction, réduisant les malentendus et accélérant l’intégration de nouveaux membres dans l’équipe. Des outils comme JSDoc peuvent même générer automatiquement des sites web de documentation à partir de ces commentaires.

Dans quel cas les commentaires sont utiles ?

Les commentaires apportent une réelle valeur lorsqu’ils expliquent le raisonnement derrière une décision technique non évidente. Le code révèle ce que vous faites, mais rarement pourquoi vous le faites ainsi. Un commentaire qui documente la raison d’une approche particulière aide les futurs lecteurs, vous y compris, à comprendre le contexte sans devoir reconstituer toute la réflexion initiale.

// On utilise un setTimeout de 0ms pour différer l'exécution
// après le rendu du DOM, évitant ainsi le blocage de l'interface
setTimeout(() => {
    traiterGrosseQuantiteDeDonnees();
}, 0);

// Calcul manuel au lieu de toFixed() car toFixed() arrondit parfois 
// de manière incohérente avec les règles comptables françaises
const montant = Math.floor(prix * 100) / 100;

Les algorithmes complexes méritent également des commentaires explicatifs. Lorsque vous implémentez un tri particulier, un calcul mathématique sophistiqué ou une logique métier alambiquée, des annotations stratégiques facilitent grandement la compréhension. Elles servent de points de repère dans un code dense qui demanderait sinon plusieurs minutes d’analyse approfondie.

function calculerDistanceHaversine(lat1, lon1, lat2, lon2) {
    // Formule de Haversine pour calculer la distance entre deux points GPS
    // Plus précise que la formule euclidienne pour les grandes distances
    const R = 6371; // Rayon de la Terre en kilomètres
    const dLat = (lat2 - lat1) * Math.PI / 180;
    const dLon = (lon2 - lon1) * Math.PI / 180;
    
    const a = Math.sin(dLat/2) * Math.sin(dLat/2) +
              Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
              Math.sin(dLon/2) * Math.sin(dLon/2);
    
    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
    return R * c;
}

Les solutions de contournement temporaires nécessitent impérativement des commentaires. Lorsque vous implémentez un correctif rapide pour un bug dans une bibliothèque tierce, ou que vous contournez une limitation du navigateur, documentez explicitement cette situation. Indiquez pourquoi ce code existe, quel problème il résout et, idéalement, dans quelles conditions il pourra être supprimé.

// WORKAROUND: Safari ne supporte pas la méthode replaceAll() avant la version 13.1
// TODO: Supprimer ce polyfill quand le support minimal sera Safari 14+
if (!String.prototype.replaceAll) {
    String.prototype.replaceAll = function(search, replacement) {
        return this.split(search).join(replacement);
    };
}

Les marqueurs TODO, FIXME et NOTE structurent le travail en cours et communiquent les intentions aux autres développeurs. Un // TODO: Ajouter la validation des emails signale clairement une fonctionnalité planifiée mais non encore implémentée. Un // FIXME: Cette fonction ne gère pas les valeurs nulles alerte sur un problème connu nécessitant correction. Ces annotations peuvent même être automatiquement détectées par des outils pour générer des listes de tâches.

La documentation des API publiques représente un cas d’usage essentiel. Lorsque vous créez une bibliothèque ou des fonctions utilisées par d’autres développeurs, les commentaires JSDoc deviennent indispensables. Ils transforment votre code en outil professionnel avec une documentation intégrée que les utilisateurs consultent directement depuis leur éditeur.

Dans quel cas les commentaires sont inutiles ?

Les commentaires deviennent superflus et nuisibles lorsqu’ils ne font que répéter ce que le code exprime déjà clairement. Un commentaire qui dit // Incrémente le compteur au-dessus de compteur++ n’apporte strictement aucune valeur. Il encombre visuellement le code sans enrichir la compréhension, et pire encore, il crée une obligation de maintenance supplémentaire.

// MAUVAIS: commentaires redondants
// Déclare une variable nom avec la valeur "Marie"
let nom = "Marie";

// Affiche le nom dans la console
console.log(nom);

// Ajoute 1 à l'âge
age = age + 1;

// BON: code auto-explicatif sans commentaire
let nom = "Marie";
console.log(nom);
age++;

Un code bien écrit avec des noms de variables et de fonctions explicites se documente lui-même. Préférer calculerPrixTotalAvecRemise(prixInitial, pourcentageRemise) plutôt que calc(p, r) élimine le besoin de commenter ce que fait la fonction. Investir du temps dans le choix de noms clairs rapporte bien davantage que multiplier les commentaires explicatifs sur du code obscur.

// MAUVAIS: code cryptique nécessitant des commentaires
// Applique la réduction et calcule le total
let t = p - (p * (r / 100));

// BON: code explicite sans besoin de commentaire
let prixApresRemise = prixInitial - (prixInitial * (pourcentageRemise / 100));

Le danger majeur des commentaires réside dans leur obsolescence. Lorsque vous modifiez du code sans mettre à jour les commentaires associés, ces derniers deviennent des sources de confusion et d’erreurs. Un développeur qui lit le commentaire avant le code se forge une compréhension erronée, le conduisant potentiellement à introduire des bugs ou à effectuer des modifications inappropriées.

// DANGEREUX: commentaire obsolète
// Retourne le prix avec une TVA de 20%
function calculerPrixFinal(prixHT) {
    // Le code a été modifié pour une TVA de 5,5% mais le commentaire reste inchangé
    return prixHT * 1.055;
}

Les commentaires expliquant le fonctionnement évident d’instructions standard polluent inutilement le code. Tout développeur JavaScript connaît la syntaxe des boucles, des conditions et des opérations de base. Commenter // Si l’utilisateur est connecté au-dessus de if (utilisateur.estConnecte) insulte l’intelligence du lecteur et noie les commentaires véritablement utiles dans un océan de bruit informationnel.

Les blocs de code commentés qui traînent indéfiniment dans le projet constituent également une mauvaise pratique. Si vous n’utilisez plus une fonction ou une section de code, supprimez-la plutôt que de la commenter. Les systèmes de contrôle de version comme Git conservent l’historique complet, vous permettant de retrouver n’importe quelle version antérieure si nécessaire. Garder du code mort commenté encombre les fichiers et sème la confusion sur ce qui est actif ou non.

// MAUVAIS: code mort qui devrait être supprimé
function traiterCommande(commande) {
    validerCommande(commande);
    
    /*
    // Ancienne méthode de paiement, plus utilisée depuis 2024
    if (commande.typePaiement === 'cheque') {
        traiterCheque(commande);
    }
    */
    
    traiterPaiementModerne(commande);
}

Enfin, les commentaires qui servent de séparateurs visuels ou de décoration révèlent généralement un problème d’organisation du code. Des lignes de symboles délimitant des sections suggèrent que le fichier devrait être restructuré en plusieurs fichiers ou fonctions plus petits. Au lieu de commenter //========== SECTION VALIDATION ==========, extrayez cette logique dans un module dédié à la validation.

Comment écrire de bons commentaires

Un bon commentaire privilégie toujours le « pourquoi » au « quoi ». Le code montre déjà ce qui se passe, votre commentaire doit révéler l’intention, le contexte ou les contraintes qui ont motivé cette approche particulière. Expliquez les décisions non évidentes, les compromis effectués ou les pièges évités plutôt que de paraphraser le code.

// MAUVAIS: explique le "quoi"
// Multiplie le prix par 0.8
let prixReduit = prix * 0.8;

// BON: explique le "pourquoi"
// Remise de 20% pour les clients fidèles selon la politique commerciale 2026
let prixReduit = prix * 0.8;

Maintenez vos commentaires synchronisés avec le code. Chaque fois que vous modifiez une fonction, vérifiez si les commentaires associés restent pertinents. Un commentaire obsolète cause plus de tort qu’aucun commentaire, car il induit activement en erreur. Si mettre à jour un commentaire vous semble fastidieux, c’est probablement le signal que ce commentaire décrit le « quoi » plutôt que le « pourquoi » et qu’il devrait être supprimé au profit d’un code plus clair.

Rédigez des commentaires concis et précis. Trois lignes claires valent mieux qu’un paragraphe verbeux. Utilisez un langage simple, direct et professionnel. Évitez l’humour ou les références obscures qui ne résisteront pas au temps ou aux différences culturelles dans une équipe internationale.

// BON: concis et informatif
// Timeout de 3 secondes pour éviter le blocage en cas de panne réseau
const TIMEOUT = 3000;

// MAUVAIS: trop verbeux
// On définit ici une constante qui représente la durée maximale en millisecondes
// pendant laquelle on va attendre une réponse avant de considérer que quelque
// chose ne va pas et d'abandonner la requête pour ne pas bloquer l'utilisateur
const TIMEOUT = 3000;

Utilisez les commentaires pour documenter les limitations, les prérequis ou les effets de bord non évidents. Si une fonction modifie l’état global, accède à une API externe ou nécessite des permissions particulières, mentionnez-le explicitement. Ces informations critiques ne transparaissent pas toujours dans le code lui-même.

Préférez améliorer le code plutôt que compenser sa complexité par des commentaires. Avant d’écrire un long commentaire expliquant une fonction compliquée, demandez-vous si vous ne pourriez pas décomposer cette fonction en plusieurs fonctions plus simples avec des noms explicites. Le meilleur commentaire reste celui qu’on n’a pas besoin d’écrire car le code parle de lui-même.