HTML Comments

HTML comments add notes, explanations, reminders, or temporarily disabled markup to an HTML document. Browsers do not render comment text as visible page content, but the comments remain part of the page source sent to the browser.

This tutorial explains HTML comment syntax, single-line and multi-line comments, commenting out HTML elements, editor shortcuts, common mistakes, and practical guidelines for writing useful comments.

What Are HTML Comments?

An HTML comment is text enclosed by the opening marker <!-- and closing marker -->. The browser recognizes this text as a comment and excludes it from the rendered webpage.

Comments are commonly used to describe page sections, document implementation decisions, leave maintenance notes, and temporarily prevent selected HTML markup from being displayed.

HTML comments are not private. Anyone who can inspect the document source or browser developer tools may be able to read them. Passwords, API keys, personal data, internal URLs, and other sensitive information must not be placed in comments.

HTML Comment Syntax

The syntax for creating a comment in HTML is straightforward:

</>
Copy
<!-- This is a comment -->

Anything placed inside the <!-- and --> markers will be treated as a comment and ignored by the browser.

The opening marker includes an exclamation mark, while the closing marker does not. Both markers are required for a complete comment.

Examples of HTML Comments

1. Single-Line Comment

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

A single-line comment places the opening marker, comment text, and closing marker on the same line. It is suitable for short notes and section labels.

2. Multi-Line Comment

</>
Copy
<!-- 
This is a comment
that spans multiple lines.
-->

HTML does not use a separate syntax for multi-line comments. The same markers can enclose text distributed across several lines.

3. Commenting Out Code

</>
Copy
<!-- 
<p>This paragraph is commented out and will not be visible on the webpage.</p>
-->

Comments can be used to temporarily disable code for testing or debugging purposes.

Commenting out markup is useful for a short test, but obsolete code should normally be deleted and recovered from version control when needed. Large blocks of unused markup make a document harder to maintain.

Common Uses of HTML Comments

1. Adding Notes and Documentation

</>
Copy
<!-- This section is for the website's navigation bar -->
<nav>
  <ul>
    <li>Home</li>
    <li>About</li>
    <li>Contact</li>
  </ul>
</nav>

A section comment is most useful when it identifies a meaningful structural boundary that is not already obvious from the markup.

2. Hiding Code During Development

</>
Copy
<!-- 
<p>This feature is under development and will be enabled soon.</p>
-->

This technique prevents the selected element from appearing while preserving the markup for a brief development test.

3. Including Instructions for Team Members

</>
Copy
<!-- Remember to update the copyright year in the footer. -->
<footer> © 2024 My Website </footer>

Maintenance comments should explain a concrete action or constraint. Update or remove them when the related requirement changes.

Marking the Start and End of an HTML Section

Comments can mark the boundaries of a long section when several nested elements make the closing tags difficult to identify.

</>
Copy
<!-- Product list starts -->
<section class="product-list">
  <article>Product details</article>
  <article>Product details</article>
</section>
<!-- Product list ends -->

Use boundary comments selectively. Clear indentation and semantic elements should remain the primary way to communicate document structure.

How to Comment Multiple Lines of HTML

To comment multiple lines, place <!-- before the first line and --> after the final line. All enclosed markup is treated as part of the comment.

</>
Copy
<!--
<section class="announcement">
  <h2>Office schedule</h2>
  <p>The office will close at 4:00 PM on Friday.</p>
</section>
-->

Do not place one complete HTML comment inside another. Nested comments are not supported reliably and can cause the browser to interpret the remaining markup incorrectly.

</>
Copy
<!-- Outer comment
  <!-- Nested comment -->
-->

Instead of nesting comments, remove the inner comment markers or divide the markup into separate non-overlapping comments.

HTML Comment Keyboard Shortcuts in Code Editors

Many code editors can add or remove HTML comment markers around the current line or selected markup. A commonly used shortcut is Ctrl+/ on Windows and Linux or Command+/ on macOS.

The exact shortcut depends on the editor, active keymap, file type, and operating system. Check the editor’s keyboard-shortcut settings when the command does not produce an HTML comment.

Best Practices for Using HTML Comments

  • Be Descriptive: Use comments to clearly explain the purpose of complex code sections.
  • Avoid Excessive Comments: Only comment when necessary to avoid cluttering the code.
  • Update Comments: Ensure comments remain relevant and accurate as the code evolves.
  • Do Not Include Sensitive Information: Avoid placing confidential information or passwords in comments.
  • Use Comments for Team Collaboration: Provide clear instructions or notes for other developers working on the project.

A useful comment explains why a decision was made, identifies a non-obvious dependency, or records a specific maintenance requirement. Comments that merely repeat clear markup add noise without providing additional context.

</>
Copy
<!-- Keep this notice before the form because validation errors link to it. -->
<p id="form-help">All fields marked required must be completed.</p>

HTML Comments Compared with CSS and JavaScript Comments

HTML comments are specific to HTML, but similar commenting techniques exist in other web technologies:

  • CSS: Comments are written using /* ... */
  • JavaScript: Comments can be single-line (//) or multi-line (/* ... */).
</>
Copy
/* CSS comment */
p {
  color: blue; /* This sets the text color to blue */
}

// JavaScript single-line comment
/*
JavaScript multi-line comment
*/

Use the comment syntax of the language being written. HTML comment markers should not be used as substitutes for CSS comments inside a stylesheet or JavaScript comments inside a script.

CSS Comment Example

</>
Copy
/* Apply consistent spacing below article paragraphs. */
article p {
  margin-bottom: 1rem;
}

JavaScript Comment Example

</>
Copy
// Select the navigation toggle button.
const menuButton = document.querySelector('.menu-button');

/*
Open or close the navigation when the button is selected.
*/
menuButton.addEventListener('click', toggleMenu);

Common HTML Comment Errors

  • Writing an incomplete opening or closing marker.
  • Attempting to nest one HTML comment inside another.
  • Assuming comments are hidden from people who inspect the page source.
  • Leaving outdated instructions that no longer match the HTML.
  • Keeping large amounts of obsolete markup commented out instead of removing it.
  • Using HTML comment syntax inside standalone CSS or JavaScript code.

When a comment appears to hide more content than expected, check that its closing --> marker is present and that no nested comment markers occur inside it.

HTML Comment Questions

How do you write a comment in HTML?

Place the comment text between <!-- and -->. For example, <!-- Navigation starts here -->.

Can an HTML comment span multiple lines?

Yes. Put the opening marker before the first line and the closing marker after the last line. HTML uses the same syntax for single-line and multi-line comments.

Can HTML comments be seen by website visitors?

Comments are not displayed as visible page content, but visitors may read them by inspecting the HTML source or developer tools. Do not store sensitive information in them.

Can HTML comments be nested?

No. Avoid placing a complete <!-- ... --> comment inside another comment because the inner closing marker may end the outer comment unexpectedly.

What is the shortcut for commenting HTML code?

Many editors use Ctrl+/ on Windows and Linux or Command+/ on macOS. The shortcut may differ depending on the editor and keymap.

HTML Comments Editorial QA Checklist

  • Verify every HTML comment starts with <!-- and ends with -->.
  • Confirm that no HTML comment is nested inside another comment.
  • Check that comments explain a useful purpose, decision, boundary, or maintenance action.
  • Remove passwords, tokens, personal data, private URLs, and other sensitive information from comments.
  • Delete outdated comments and large blocks of obsolete commented-out markup.
  • Confirm CSS and JavaScript examples use their own comment syntax rather than HTML comment markers.

Summary of HTML Comments

HTML comments use the syntax <!-- comment -->. They can document markup, identify sections, provide maintenance notes, or temporarily prevent HTML elements from being rendered. Comments may span multiple lines, but they should not be nested and must never contain sensitive information.