HTML Comments | Add Notes to HTML Code

Understanding HTML Comments

HTML comments allow you to place notes and explanations directly inside your markup without displaying them as visible webpage content.

Comments can help organize large documents, explain why markup was written a certain way, leave notes for other developers, or temporarily remove sections of HTML while testing. They are useful for maintaining code, but they should be used carefully and kept clear and relevant.

HTML Comment Syntax

An HTML comment begins with . Anything placed between these markers is treated as a comment rather than visible document content.

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

The browser does not normally display the comment on the rendered webpage.

Comments can appear between elements throughout an HTML document:

<h1>About Our Company</h1>
<!-- Introductory paragraph -->
<p>We have been serving customers since 1995.</p>

The comment describes the markup for someone reading the source code but does not become part of the visible page content.

Single-Line Comments

A short comment can be written on a single line when only a brief note is needed.

<!-- Main navigation -->
<nav>
  ...
</nav>

Single-line comments are useful for identifying major areas of a document or leaving short maintenance notes.

Another common example is marking the beginning or end of a section:

<!-- Featured Products -->
<section>
  ...
</section>

Keep these comments short enough that they remain easy to scan while reading the surrounding HTML.

Multi-Line Comments

A comment can span multiple lines when a longer explanation is needed.

<!--
This section displays featured products.
The product list is updated each month.
-->
<section>
  ...
</section>

The opening and closing comment markers may appear on separate lines, while the explanatory text remains between them.

Multi-line comments are useful when documenting a decision or giving instructions that would be difficult to understand in a single short line.

Organizing HTML with Comments

Comments can make a long HTML document easier to navigate by identifying major sections in the source code.

<!-- Header -->
<header>
  ...
</header>
<!-- Main Content -->
<main>
  ...
</main>
<!-- Footer -->
<footer>
  ...
</footer>

This can be especially useful when several developers work on the same project or when you return to a large document after not editing it for some time.

However, semantic HTML and consistent indentation should still provide most of the document's structure. Comments should support well-organized markup rather than compensate for confusing source code.

Temporarily Commenting Out HTML

Comments are sometimes used to temporarily prevent a section of markup from being rendered while testing or editing a webpage.

For example:

<!--
<section>
  <h2>Holiday Sale</h2>
  <p>Save 20 percent this week.</p>
</section>
-->

The section remains in the source file but is not rendered as normal page content while it is inside the comment.

This can be convenient during development, but large blocks of unused commented-out code should not be left in a finished document indefinitely. Old code is usually better preserved through backups or version control rather than accumulating inside the page source.

Comments Remain in the Source Code

An HTML comment is hidden from the rendered webpage, but it is not private. Anyone who can view the page source or inspect the document may be able to read the comment.

For this reason, never place passwords, private account information, security details, confidential notes, or other sensitive information inside HTML comments.

For example, this would be inappropriate:

<!-- Admin password: secret123 -->

The fact that the browser does not display the comment visually does not make the information secure.

Nested Comments

HTML comments should not be nested inside other HTML comments.

Incorrect:

<!--
Main section
<!-- Featured products -->
<section>
  ...
</section>
-->

The inner comment markers interfere with the surrounding comment syntax and can produce unexpected parsing results.

If a block of HTML already contains comments and you want to comment out the entire block, remove or rewrite the inner comments first rather than nesting comment markers.

Common Comment Mistakes

HTML comments use a specific syntax, and malformed comments can make the source confusing or cause the browser to interpret the markup differently than intended.

Common mistakes include:

Forgetting the opening <!-- marker.
Forgetting the closing --> marker.
Trying to nest one HTML comment inside another.
Leaving large amounts of obsolete code commented out permanently.
Using comments to explain markup that should be made clearer through better HTML structure.
Placing passwords or other sensitive information inside comments.
Assuming comments cannot be viewed by website visitors.

When comments are kept simple and correctly formatted, they can make source code easier to understand without distracting from the markup itself.

HTML Comment Best Practices

Good comments explain useful information that is not already obvious from clear HTML markup.

Use comments to explain important decisions or unusual markup.
Use short section comments when they make long documents easier to navigate.
Keep comments accurate when the surrounding code changes.
Remove outdated comments that no longer describe the markup correctly.
Avoid excessive comments that make the source harder to scan.
Do not store sensitive or confidential information in comments.
Avoid permanently keeping large blocks of unused markup inside comments.
Use clear semantic HTML and consistent indentation so the markup can explain much of its own structure.

The most useful comments answer questions such as why something was written a certain way rather than simply repeating what the HTML already shows.

Summary

HTML comments begin with . They allow notes, explanations, and temporarily disabled markup to remain in the source without appearing as normal visible webpage content.

Comments can improve organization and maintainability when they are concise and meaningful. They should not be nested, should not be used to store sensitive information, and should not replace clear semantic markup or consistent formatting.