Les deux types de commentaires
En JavaScript, il existe deux syntaxes de commentaire. Le commentaire sur une ligne commence par // et s'étend jusqu'à la fin de la ligne :
Un commentaire multiligne commence par /* et se termine au prochain */ rencontré. Il peut s'étaler sur autant de lignes que nécessaire :
Les deux formes sont totalement ignorées par le moteur JavaScript. Elles existent pour les humains — pour toi, pour tes collègues, et pour le toi du futur qui relira ce code dans six mois.
Commentaire une ligne en JavaScript
// est la syntaxe que tu utiliseras le plus souvent. Tout ce qui suit // sur la même ligne est considéré comme un commentaire ; dès la ligne suivante, on repart sur du code :
Un commentaire en fin de ligne (juste après une instruction) fait très bien l'affaire pour une note courte. Mais dès que la note devient assez longue pour passer à la ligne, mieux vaut la déplacer au-dessus du code sur sa propre ligne : les commentaires de fin de ligne trop longs finissent tronqués dans les éditeurs, et personne ne les lit.
Le commentaire multiligne en JavaScript
La syntaxe /* */ devient intéressante dans deux situations : quand un commentaire tient sur plusieurs lignes, et quand il doit s'insérer au milieu d'une expression.
Un piège classique : les commentaires multilignes ne s'imbriquent pas. Le premier */ rencontré ferme le commentaire, même si tu croyais encore être dans le bloc englobant :
/* extérieur /* intérieur */ encore extérieur */
// SyntaxError — le premier */ a fermé le bloc,
// et "encore extérieur */" est maintenant du code invalide.
Si tu dois commenter du code qui contient déjà des /* */, utilise plutôt // sur chaque ligne.
Désactiver temporairement du code
Pendant le débogage, il arrive souvent qu'on veuille désactiver quelques lignes le temps d'un test. Les deux formes de commentaire font le boulot :
Tous les éditeurs ont un raccourci pour ça — Ctrl+/ sous Windows/Linux, Cmd+/ sous Mac — qui bascule // sur les lignes sélectionnées. Apprends-le une bonne fois pour toutes, tu t'en serviras tous les jours.
Le code commenté est censé rester temporaire. Évite de committer des cimetières de code mort avec un // ancienne version, on garde au cas où au-dessus. Git se souvient très bien du code d'avant à ta place. Supprime-le.
Commenter le pourquoi, pas le quoi
C'est LA règle qui sépare les commentaires utiles du bruit inutile. Le code montre déjà ce qu'il fait. Un bon commentaire explique pourquoi il le fait.
Du bruit :
Ces commentaires n'apportent rien de plus que ce que le code dit déjà. Regardez la différence :
Dans les deux cas, le commentaire apporte une info qu'on ne peut pas deviner en lisant le code : une contrainte externe, un comportement documenté ailleurs. C'est ça, le bon niveau. Si tu peux supprimer le commentaire sans perdre personne au passage, c'est qu'il ne servait à rien.
JSDoc : des commentaires que les outils savent lire
JSDoc est une convention qui permet d'écrire des commentaires de bloc structurés pour décrire tes fonctions. Les éditeurs et les vérificateurs de types les exploitent pour te fournir une meilleure autocomplétion et des infos au survol :
L'ouverture /** (avec deux étoiles) est ce qui distingue un commentaire JSDoc d'un simple commentaire multiligne JavaScript classique. Pas besoin de coller du JSDoc sur chaque fonction — il prend surtout son sens sur les API publiques, les utilitaires partagés, et partout où les types ne sautent pas aux yeux à la lecture du code.
Quelques bonnes habitudes à garder
- Placez le commentaire juste à côté du code concerné. Un commentaire situé dix lignes au-dessus finit tôt ou tard par se désynchroniser quand le code évolue.
- Mettez le commentaire à jour dès que vous modifiez le code. Un commentaire périmé est pire que pas de commentaire du tout — il ment activement à la personne qui lira le code après vous.
- Préférez un meilleur nom plutôt qu'un commentaire de plus.
const d = 86400000;réclame un commentaire.const MILLISECONDS_PER_DAY = 86_400_000;non. - Signalez les soucis temporaires avec
TODO:ouFIXME:. La plupart des éditeurs les mettent en surbrillance, et c'est facile à retrouver avec un grep plus tard.
Petite note sur les commentaires HTML vs JavaScript
Si tu écris du JavaScript au sein d'un fichier HTML, attention à ne pas mélanger les deux syntaxes de commentaire. Le HTML utilise <!-- -->, tandis que le JavaScript s'appuie sur // et /* */. À l'intérieur d'une balise <script>, seules les formes JavaScript fonctionnent :
<script>
// Correct — commentaire JS à l'intérieur de <script>
/* Également correct */
<!-- Incorrect — ceci est un commentaire HTML et cassera votre JS -->
console.log("hi");
</script>
Les navigateurs ont historiquement toléré <!-- --> à l'intérieur des scripts pour des raisons de compatibilité avec d'anciens navigateurs, mais considère ça comme une relique et passe à autre chose.
La suite : déclarer des variables
Maintenant que tu sais annoter ton code, il est temps d'en écrire. JavaScript propose trois façons de déclarer une variable — let, const et var — et choisir la bonne, c'est la première vraie décision que tu prendras sur chaque ligne. C'est ce qu'on voit juste après.
Questions fréquentes
Comment écrire un commentaire en JavaScript ?
Utilisez // pour un commentaire sur une seule ligne : tout ce qui suit sur la ligne est ignoré par le moteur. Pour plusieurs lignes, il y a /* ... */. Les deux syntaxes fonctionnent partout dans un fichier .js, y compris dans les balises <script> d'un fichier HTML.
Quelle est la différence entre // et /* */ en JavaScript ?
// s'arrête à la fin de la ligne courante. /* */ commence à /* et se termine au premier */ rencontré, donc il peut couvrir plusieurs lignes ou s'insérer en plein milieu d'une expression. En pratique : // pour une note rapide, /* */ quand vous avez besoin de plusieurs lignes ou d'annoter une partie d'expression.
Comment commenter un bloc de code en JavaScript ?
Soit vous l'entourez avec /* */, soit vous préfixez chaque ligne par //. La plupart des éditeurs ont un raccourci : Ctrl+/ (Cmd+/ sur Mac) bascule les // sur toutes les lignes sélectionnées. Évitez d'imbriquer un /* */ dans un autre /* */ : le premier */ ferme le commentaire extérieur et vous tombez sur une erreur de syntaxe.
Quand faut-il écrire un commentaire ?
Commentez le pourquoi, pas le quoi. Si le code fait quelque chose de non évident — un contournement, une règle métier, une astuce de performance — expliquez la raison. Inutile de paraphraser ce que le code dit déjà. Un nom de variable ou de fonction bien choisi rend la plupart des commentaires superflus.
