HTML Comment Syntax

Technical Deep Dive & Specifications

The Anatomy of an HTML Comment

An HTML comment consists of three components:

1. Comment Start Sequence: Exactly <!-- (Less-than, exclamation mark, hyphen, hyphen).
2. Comment Data: Zero or more characters representing the text payload.
3. Comment End Sequence: Exactly --> (Hyphen, hyphen, greater-than).

<!-- This is comment data -->

The WHATWG HTML Tokenizer State Machine

The HTML5 living standard specifies a deterministic finite state machine (FSM) for parsing markup. When the tokenizer encounters <, it evaluates the subsequent characters:

  [ Data State ]
        |  encounter '<'
        v
  [ Tag Open State ]
        |  encounter '!'
        v
  [ Markup Declaration Open State ]
        |  encounter '--'
        v
  [ Comment Start State ]
        |  any character (e.g. 'A')
        v
  [ Comment State ] <----------- (consumes comment characters)
        |  encounter '-'
        v
  [ Comment End Dash State ]
        |  encounter '-'
        v
  [ Comment End State ]
        |  encounter '>'
        v
  [ Data State ] (Emits Comment Token to Tree Builder)

WHATWG Syntax Rules & Prohibited Patterns

According to the WHATWG specification, valid HTML comments must adhere to strict lexical constraints:

[!NOTE] Even though modern browsers recover gracefully from parse errors (error-recovery mode), invalid comment syntax can cause unpredictable DOM structures in older tools, XML/XHTML parsers, or strict linters.

Comments in the DOM: The Comment Interface

A common misconception is that comments disappear during parsing. In reality, the browser's Tree Builder constructs a CommentNode for every comment encountered.

In the Web IDL hierarchy:

  EventTarget
      └── Node (nodeType === 8 for Node.COMMENT_NODE)
            └── CharacterData
                  ├── Text (nodeType === 3)
                  ├── CDATASection (nodeType === 4)
                  ├── ProcessingInstruction (nodeType === 7)
                  └── Comment (nodeType === 8)

Inspecting and Querying Comments via JavaScript:

// Accessing child nodes of an element
const header = document.querySelector('header');

header.childNodes.forEach(node => {
  if (node.nodeType === Node.COMMENT_NODE) {
    console.log("Found comment:", node.nodeValue); // or node.data
  }
});

// Creating a comment dynamically
const newComment = document.createComment("Generated dynamically by script");
document.body.appendChild(newComment);

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Line 8–10 (<!-- === ... HERO SECTION ... === -->): Structured banner comment marking the start of a major functional UI module.
• Line 11 (<section id="hero">): The semantic DOM container element.
• Line 14 (<!-- <button ...> ... -->): Temporarily commented-out (disabled) HTML markup with an explanatory note. The browser does not render this button.
• Line 26–36 (<script>...childNodes.forEach...</script>): JavaScript traversing the heroSection child nodes. When it encounters node.nodeType === 8 (Node.COMMENT_NODE), it accesses node.data and logs it to the UI.

Expected Browser Render Output

(Notice that the secondary button is not rendered visually, but its comment node exists in the DOM and is extracted via script).

Supercharge Your Workflow
The developer platform built for high-performance teams.
[Get Started Free]

DOM Comment Inspector Log:
• Index [1] (Node.COMMENT_NODE): "========================================================"
• Index [3] (Node.COMMENT_NODE): "HERO SECTION: Primary user conversion banner"
• Index [5] (Node.COMMENT_NODE): "========================================================"
• Index [9] (Node.COMMENT_NODE): "<button class="btn-secondary">Learn More</button> (Temporarily disabled for Q3 launch)"