HTML Comments

An HTML comment is a piece of text inside your markup that the browser parses but never displays or renders visually. Comments let you leave notes for yourself and other developers directly in the source code — explaining tricky sections, marking where a feature starts and ends, or temporarily disabling a block of markup without deleting it.

Comments matter because HTML files are often maintained by teams over years, and the reasoning behind a particular structure is not always obvious just from reading tags. A well-placed comment can save the next developer (often a future version of yourself) a lot of guesswork.

Overview / How it works

When a browser’s HTML parser reads a document, it builds the DOM (Document Object Tree) node by node. Most content becomes element nodes, text nodes, or attribute nodes. A comment becomes a special kind of node called a Comment node. This node exists in the DOM tree — you can find it with JavaScript’s DOM APIs — but it carries no visual or semantic meaning. The rendering engine skips comment nodes entirely when painting the page, so nothing about a comment’s content is ever shown to the person viewing the page.

This is fundamentally different from an element like span or p, which the browser turns into a rendered box on the page (even if that box is empty). A comment is not a presentational or semantic element at all — it is metadata about the source code, meant only for people reading the code (or, in some documented scenarios, for tools that scan HTML source).

Comments are not a security boundary

It is important to understand that comments are only invisible in the rendered page. Anyone who views the page source, opens browser developer tools, or fetches the raw HTML over the network can read your comments in full. Never put passwords, API keys, internal URLs, or other sensitive information inside an HTML comment — it is exactly as exposed as any other text in the file.

Syntax

An HTML comment always begins with <!-- and ends with -->. Everything between those markers is ignored by the renderer.

<!-- This is a comment and will not be displayed -->

Part	Meaning
<!--	Opening delimiter. Marks the start of the comment. No space is required after it, though one is conventional for readability.
comment text	Any text, including line breaks. It must not contain the literal sequence -- (two consecutive hyphens) except at the very end, right before the closing delimiter.
-->	Closing delimiter. Marks the end of the comment. Every comment you open must be closed with this exact sequence.

Comments can span a single line or many lines, and they can be placed almost anywhere in the document body or head — between elements, inside an element’s children, or even inside attribute lists is not allowed (a comment cannot open in the middle of a tag’s own attributes; it must sit between complete tags).

Examples

Example 1: A simple single-line comment

<p>Welcome to our site.</p>
<!-- TODO: add a call-to-action button here -->
<p>Browse our latest articles below.</p>

Result: The browser displays two paragraphs of text: “Welcome to our site.” followed by “Browse our latest articles below.” The comment line is completely invisible on the page; it only exists for a developer reading the source file.

This is the most common use of comments: a short reminder about future work, left inline where the change will eventually happen.

Example 2: Multi-line comments explaining a section

<!--
  Navigation bar
  Contains links to the main site sections.
  Update this list whenever a new top-level page is added.
-->
<nav>
  <ul>
    <li><a href="/home">Home</a></li>
    <li><a href="/about">About</a></li>
    <li><a href="/contact">Contact</a></li>
  </ul>
</nav>

Result: The browser renders a navigation region containing a bulleted (unordered) list of three links: Home, About, and Contact. The multi-line comment above it produces no visible output at all — it exists purely to document the purpose of the nav block for anyone editing the file later.

Comments don’t need to fit on one line. Everything between <!-- and -->, including line breaks, is treated as comment content.

Example 3: Temporarily disabling markup (“commenting out”)

<div>
  <h3>Newsletter Signup</h3>
  <!--
  <form action="/subscribe" method="post">
    <label for="email">Email address:</label>
    <input type="email" id="email" name="email">
    <button type="submit">Subscribe</button>
  </form>
  -->
  <p>Signups are temporarily paused. Check back soon!</p>
</div>

Result: The browser renders a heading “Newsletter Signup” followed by the paragraph “Signups are temporarily paused. Check back soon!”. The entire form element — the label, input field, and submit button — is wrapped inside a comment, so none of it is parsed as active markup or shown on the page.

This technique, often called “commenting out”, is a fast way to disable a block of markup during development without deleting it, so it can be restored later simply by removing the comment delimiters.

How it works step by step

• The browser’s HTML tokenizer scans the byte stream and detects the exact sequence <!--, which switches it into “comment parsing” mode.
• While in comment mode, the tokenizer does not look for tags, attributes, or entities — it simply accumulates raw text until it finds the closing sequence -->.
• Once the closing delimiter is found, the parser creates a single Comment node containing the accumulated text and inserts it into the DOM tree at that position, as a sibling of the surrounding elements.
• During rendering, the layout and paint stages walk the DOM but skip Comment nodes entirely — they contribute zero width, height, or visual output, unlike an empty element which can still occupy space.
• Because comment content is never treated as markup, any tags typed inside a comment (like the form in Example 3) are not parsed as elements at all — they remain inert text until the comment is removed.

Common Mistakes

Mistake 1: Nesting comments

You cannot nest one comment inside another. The parser ends the comment at the first --> it finds, so anything after that point is treated as regular markup again.

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

Here the comment actually closes right after “inner comment”, and the remaining text still outer? --> is parsed as ordinary page content, which is almost never what was intended.

Corrected: use one comment block, or remove the section entirely instead of trying to nest comments:

<!-- Outer comment, inner comment merged into one note -->

Mistake 2: A double hyphen inside the comment text

<!-- Sale ends in 5--10 days -->

The sequence -- is not allowed inside comment content because it is easily confused with, or can even prematurely trigger, the closing delimiter in some parsing situations. Browsers are lenient about this in practice, but it is invalid HTML and different tools may handle it inconsistently.

Corrected: rephrase to avoid consecutive hyphens:

<!-- Sale ends in 5 to 10 days -->

Mistake 3: Forgetting to close a comment

<!-- This note was never closed
<p>This paragraph disappears!</p>

Without a closing -->, the comment silently swallows everything that follows, including entire elements, until either the parser finds a closing delimiter further down the file or the document simply ends. This is a sneaky bug because nothing throws an error — content just stops appearing.

Corrected: always pair every opening delimiter with a closing one:

<!-- This note is properly closed -->
<p>This paragraph renders correctly.</p>

Best Practices

• Use comments to explain why something is done a certain way, not to restate what the markup obviously already shows.
• Never store secrets, credentials, internal links, or personal data in comments — they are fully visible in the page source to anyone.
• Remove leftover “commented-out” experimental markup before shipping to production; stale commented code adds confusion and file size over time.
• Use consistent markers like <!-- TODO: ... --> or <!-- FIXME: ... --> so notes are easy to search for across a project.
• Add a comment before major structural sections (header, main navigation, footer) in long documents to make the file easier to scan.
• Avoid double hyphens (--) inside comment text to stay within the valid HTML specification.
• Do not rely on comments as a substitute for proper documentation elsewhere; they are for source-level context, not user-facing or project-level docs.

Practice Exercises

• Write an HTML fragment containing a heading and a paragraph. Add a comment above each explaining what content should eventually replace the placeholder text.
• Take a small block of markup containing a list of three items, and “comment out” the entire list so it no longer renders, while leaving a sibling paragraph visible above and below it.
• Identify and fix the bug in this snippet, then rewrite it correctly: <!-- Section start <!-- reminder --> still hidden? --> <p>Text</p>. Explain in your own words which parts actually render once the parser has processed it.

Summary

• HTML comments start with <!-- and end with -->; everything between is ignored by the renderer.
• Comments become Comment nodes in the DOM but produce no visual output and are skipped during rendering.
• Comments are visible to anyone viewing page source — never put sensitive information inside one.
• Comments cannot be nested, and content should avoid consecutive hyphens (--).
• A missing closing delimiter silently hides all following content until a closing sequence is found.
• Comments are a great tool for TODOs, section labels, and temporarily disabling markup during development.