Commentaires HTML

Un commentaire HTML est une note dans votre balisage que le navigateur ignore : il n'est pas affiché sur la page et n'a aucun effet sur la mise en page. Les commentaires existent uniquement pour les personnes qui lisent et maintiennent le code source. Ils vous permettent d'expliquer pourquoi un morceau de balisage existe, de laisser des rappels pour plus tard, et de désactiver temporairement du code sans le supprimer.

Cette page couvre la syntaxe des commentaires, les commentaires sur une ligne et sur plusieurs lignes, les règles qui rendent un commentaire valide (et les erreurs qui le brisent), comment commenter du code pendant le débogage, ainsi que les commentaires conditionnels Internet Explorer hérités que vous pouvez encore rencontrer dans d'anciens projets.

Syntaxe

Un commentaire s'ouvre avec <!-- et se ferme avec -->. Tout ce qui se trouve entre ces marqueurs est ignoré par le navigateur :

<!-- This is an HTML comment -->

Vous pouvez placer un commentaire sur sa propre ligne, ou après du balisage sur la même ligne :

<p>Total price</p>
<!-- TODO: pull this value from the cart, not hard-coded -->
<p>$42.00</p> <!-- includes tax -->

Le --> de fermeture est obligatoire. Si vous l'oubliez, le navigateur continue de traiter tout ce qui suit comme faisant partie du commentaire jusqu'à ce qu'il trouve le prochain --> (ou la fin du document), ce qui masque silencieusement des portions de votre page — un bug courant et déroutant.

Pourquoi utiliser des commentaires

• Expliquer l'intention. Le code montre ce qui se passe ; un commentaire peut enregistrer pourquoi. « Pourquoi cette <div> est-elle vide ? » trouve sa réponse dans une note d'une ligne.
• Collaboration. Dans une base de code partagée, les commentaires indiquent aux membres de l'équipe comment une section est censée fonctionner.
• Notes TODO / FIXME. Marquer les travaux inachevés ou les problèmes connus pour les retrouver facilement plus tard (<!-- TODO: add alt text -->).
• Débogage. Masquer temporairement du balisage pour isoler un problème sans perdre le code d'origine.

Commentaires sur une ligne et sur plusieurs lignes

La même syntaxe <!-- --> fonctionne pour une ligne ou plusieurs. Un commentaire multiligne s'étend simplement sur plusieurs lignes entre les marqueurs d'ouverture et de fermeture :

<!-- This is a single-line comment -->

<!--
  This is a multi-line comment.
  Everything here is ignored by the browser,
  no matter how many lines it spans.
-->
<p>This paragraph is visible.</p>

HTML n'a pas de syntaxe de commentaire de bloc séparée — contrairement à CSS, qui utilise /* ... */, ou à JavaScript, qui utilise // et /* ... */. En HTML, c'est toujours <!-- -->.

Commenter du code pour le débogage

Entourer du balisage d'un commentaire est un moyen rapide de le désactiver sans le supprimer. C'est inestimable lorsque vous cherchez quel élément cause un problème :

<h1>The main heading</h1>

<!-- Temporarily disabled while debugging the layout
<aside>
  <p>This sidebar is hidden for now.</p>
</aside>
-->

<a href="https://www.w3docs.com">Homepage</a>

L'élément <aside> ci-dessus n'est pas rendu et le navigateur ne le construit même pas dans le DOM. Lorsque vous avez terminé, supprimez <!-- et --> pour rétablir le code.

Commentaires valides et invalides

Un commentaire obéit à quelques règles. Si vous les enfreignez, le navigateur peut traiter votre commentaire comme du texte, ou avaler du balisage que vous vouliez conserver.

Vous ne pouvez pas imbriquer des commentaires. Le premier --> ferme le commentaire, donc le second --> devient du texte errant sur la page :

<!-- outer comment <!-- inner comment --> still inside? -->

Ici, le commentaire se termine au premier -->. Le reste still inside? --> est rendu sous forme de texte visible — ce n'est presque jamais ce que vous souhaitiez.

Évitez -- à l'intérieur d'un commentaire. Selon la spécification HTML, le texte d'un commentaire ne doit pas contenir -- sauf dans le cadre du --> de fermeture. Il ne doit pas non plus commencer par > ou ->. Ceux-ci sont valides :

<!-- A perfectly valid comment -->
<!-- Visit the section "Pricing" below -->

Et ceux-ci sont problématiques :

<!-- Don't use a -- double dash inside -->   <!-- the "--" can confuse parsers -->
<!--> Starts with > — invalid -->
<!-- Missing the closing marker     <-- the rest of the page may vanish

La meilleure habitude : ouvrir avec <!--, rédiger votre note en utilisant des tirets simples ou des mots, et toujours fermer avec -->.

Essayez : commentaires HTML dans un document complet

<!DOCTYPE html>
<html>
  <head>
    <title>The title of the document.</title>
  </head>
  <body>
    <h1>The main heading</h1>
    <!-- <p>We want to hide this paragraph temporarily.</p> -->
    <a href="https://www.w3docs.com">Homepage</a>
    <!-- TODO: this link will point to the homepage -->
  </body>
</html>

Le navigateur n'affiche que le titre et le lien. Les deux lignes commentées ne produisent rien à l'écran, comme le montre l'aperçu en direct ci-dessous.

Commentaires conditionnels (Internet Explorer hérité)

Les anciennes versions d'Internet Explorer (IE 5 à IE 9) prenaient en charge une syntaxe de commentaire conditionnel spéciale. Pour tout autre navigateur, cela ressemblait à un commentaire ordinaire et était ignoré, mais IE lisait et exécutait le balisage à l'intérieur lorsque la condition correspondait :

<!--[if IE]>
  <link rel="stylesheet" href="ie-only.css">
<![endif]-->

<!--[if lt IE 9]>
  <p>You are using an old version of Internet Explorer.</p>
<![endif]-->

C'était autrefois une façon standard de livrer des CSS ou des scripts uniquement à des versions spécifiques d'IE. Les commentaires conditionnels sont obsolètes. Internet Explorer 10 a abandonné leur prise en charge, et les navigateurs modernes ne les ont jamais supportés, donc vous ne devriez pas utiliser cette technique dans du nouveau code. Ils sont présentés ici uniquement pour que vous les reconnaissiez dans des projets hérités.

Où les commentaires peuvent et ne peuvent pas aller

Tous les navigateurs modernes prennent en charge les commentaires HTML et ignorent leur contenu, donc la syntaxe peut être utilisée en toute sécurité partout où votre balisage a besoin d'être expliqué.

Exercice