(Le Code Parle… Mais les Humains Ont Besoin de Sous-Titres)
Un jour, vous ouvrez un ancien projet.
Vous regardez l’écran.
Le code vous regarde en retour.
Un silence tendu s’installe.
« Est-ce que c’est vraiment moi qui ai écrit ça ? »
C’est exactement à ce moment-là que vous comprenez la valeur des commentaires.
Les commentaires en JavaScript peuvent sembler petits, mais ils évitent de grandes catastrophes.
Bien utilisés, ils renforcent la communication au sein de l’équipe.
Mal utilisés, ils se transforment en cimetière de code.
Aujourd’hui, nous n’allons pas considérer les commentaires comme un simple « // écrire une explication ».
Nous allons les voir comme une arme stratégique du clean code.
Prêt ? Commençons.
1️⃣ Commentaires sur une seule ligne (//)
(Des Chuchotements dans la Marge de Votre Code)
Les commentaires sur une seule ligne sont rapides, pratiques et parfaits pour les idées instantanées.
// Année de naissance de l'utilisateur
const birthYear = 1998;
Simple. Mais voici l’essentiel :
Les commentaires sur une seule ligne donnent généralement du contexte.
🎯 Quand les utiliser ?
- Pour expliquer la logique métier derrière une ligne
- Pour de petits avertissements
- Pour désactiver temporairement du code pendant le débogage
⚠️ Utiliser les commentaires pour déboguer
const price = 100;
const discount = 20;
// const total = price - discount;
const total = price;
console.log(total);
Ici, la remise est temporairement désactivée.
Mais attention :
Si le temporaire devient permanent, votre projet se transforme en désordre.
👉 Astuce pro :
Supprimez le code commenté temporaire une fois le travail terminé.
2️⃣ Commentaires multi-lignes (/* */)
(Un Mini-Documentaire à l’Intérieur de Votre Code)
Les commentaires multi-lignes sont utilisés pour des explications plus détaillées.
/*
Cette fonction :
- Nettoie les données brutes de l'utilisateur
- Supprime les espaces inutiles
- Convertit le texte en majuscules
*/
function normalizeInput(input) {
return input.trim().toUpperCase();
}
Le code ici est court.
Mais dans les projets réels, les choses deviennent complexes.
🎯 Exemple réel
/*
Format de date reçu depuis l'API :
"2026-02-13T08:15:30Z"
Cette fonction :
1. Convertit la chaîne en objet Date
2. L’adapte au fuseau horaire local
3. Retourne une chaîne lisible pour l’interface
*/
function formatDate(apiDate) {
const date = new Date(apiDate);
return date.toLocaleString();
}
Ce commentaire dit aux futurs développeurs :
« Il y a une logique ici. Ce n’est pas écrit au hasard. »
3️⃣ Pourquoi écrivons-nous des commentaires ? (La Philosophie)
Le code montre ce qu’il fait.
Les commentaires expliquent pourquoi il le fait.
❌ Mauvais exemple
// Multiplier le nombre par 2
const result = number * 2;
Inutile.
✅ Bon exemple
// L’API renvoie une valeur décimale au lieu d’un pourcentage, donc on multiplie par 100
const percentage = apiValue * 100;
Ici, nous avons du contexte.
Nous avons une raison.
Nous répondons à la question :
« Pourquoi avons-nous fait quelque chose qui semble étrange ? »
4️⃣ Les Commentaires Sauvent des Vies dans la Logique Complexe
Dans les projets réels, certaines lignes de code…
mettent votre santé mentale à l’épreuve.
const finalPrice =
user.isPremium && cart.total > 500
? cart.total * 0.8
: cart.total;
Cette seule ligne contient du drame.
Clarifions-la :
// Si l'utilisateur est premium et que le panier dépasse 500, appliquer 20 % de réduction
const finalPrice =
user.isPremium && cart.total > 500
? cart.total * 0.8
: cart.total;
Maintenant, c’est plus humain.
5️⃣ JSDoc : Commentaires de Niveau Professionnel
Dans les grands projets, les commentaires ne sont pas seulement des explications.
Ce sont des outils de documentation.
/**
* Additionne deux nombres
* @param {number} a - Premier nombre
* @param {number} b - Deuxième nombre
* @returns {number} Le résultat total
*/
function sum(a, b) {
return a + b;
}
Pourquoi est-ce important ?
- Les IDE fournissent des suggestions intelligentes
- La vérification des types devient plus simple
- Énorme avantage dans les projets en équipe
Si vous n’utilisez pas TypeScript, JSDoc vaut de l’or.
6️⃣ TODO, FIXME et Dette Technique
Dans la vraie vie, aucun projet n’est « parfait ».
// TODO : Rendre cette fonction asynchrone
// FIXME : L’API génère une erreur lorsqu’elle retourne null
// HACK : Solution temporaire
Ces étiquettes :
- Améliorent la communication d’équipe
- Rendent la dette technique visible
- Apportent de l’ordre au chaos
Mais souvenez-vous :
Les TODO ne doivent pas vivre éternellement.
7️⃣ Trop de Commentaires Peut Être Nuisible
Voici la partie critique.
// Déclarer une variable
let count = 0;
// Augmenter de 1
count++;
// Afficher dans la console
console.log(count);
Cela ressemble à un tutoriel pour débutants.
Dans un projet réel, c’est inutile.
Écrivez plutôt un code plus clair :
let loginAttemptCount = 0;
loginAttemptCount++;
console.log(loginAttemptCount);
Si le nommage est bon, les commentaires deviennent moins nécessaires.
8️⃣ Dois-je Commenter ou Simplifier le Code ?
Posez-vous la question :
« Ce code a-t-il besoin d’un commentaire pour être compris ? »
Si oui…
Peut-être faut-il simplifier le code.
Exemple :
// Bloquer l'accès si l'utilisateur est actif mais pas admin
if (user.isActive === true && user.role !== "admin") {
Réécrivons-le plus clairement :
const isRestrictedUser =
user.isActive && user.role !== "admin";
if (isRestrictedUser) {
Maintenant, moins de commentaires sont nécessaires.
9️⃣ La Plus Grande Vérité
Les commentaires sont :
Des lettres à votre futur vous.
Des guides pour vos coéquipiers.
Des cartes de la logique métier complexe.
Mais :
Un mauvais code ne peut pas être sauvé par des commentaires.
Les commentaires ne remplacent pas une structure propre.
Les commentaires inutiles polluent votre code.
🎬 Conclusion
Le code est pour les ordinateurs.
Les commentaires sont pour les humains.
Et la phrase la plus dangereuse dans le développement logiciel est :
« Je m’en souviendrai. »
Non.
Vous ne vous en souviendrez pas.
Écrivez des commentaires.
Mais écrivez-les intentionnellement.
Soyez concis.
Expliquez la raison.
Donnez du contexte.
Parce que six mois plus tard…
Votre meilleur ami dans ce projet
sera le commentaire que vous avez écrit.
