Comments in HTML

Learn how to add comments in HTML, comment out HTML for fast debugging, write html multiline comments, and follow best practices for clean, team-friendly code.

You write some HTML code today. Everything works perfectly. You come back to it two weeks later and stare at the screen wondering, “Why did I write this?” or “What is this block even doing?”

This is the moment you realize how powerful comments in HTML truly are.

A comment is a piece of text you write inside your HTML file that the browser completely ignores. It does not show up on your webpage. It is only there for you, your future self, or your teammates. But do not underestimate it. Knowing how to properly add comments in HTML is one of the habits that separates a sloppy coder from a clean, professional developer.

In this tutorial, you will learn everything: the syntax, when and how to use them, how to comment out HTML for debugging, best practices, and how to use them to make your team’s life easier.

If you are new here, make sure you have read our Introduction to HTML first, and also our guide on HTML Tags, Elements, and Attributes so you already understand how HTML is structured.

01What Are Comments in HTML?

When you write a webpage, your HTML file is full of tags, content, and structure. But sometimes you need to leave a note for yourself or explain what a piece of code does. That is what comments in HTML are for.

A comment in HTML starts with . Everything between these two markers is a comment. The browser sees it, but it never renders it on the screen. It is invisible to your visitors.

Here is the simplest possible example:

<!-- This is a comment in HTML -->
<p>This paragraph will show on the page.</p>
<!-- This line will NOT show on the page -->

Open that in a browser. You will only see the paragraph text. The two comment lines are completely invisible. That is the core idea.

Anatomy of an HTML Comment

    <!–

    Your comment text goes here

    –>

Opening marker: <!--

Your note or disabled code

Closing marker: -->

02How to Add Comments in HTML

The syntax is the same every time. There is only one way to add comments in HTML, and it always uses  to close.

You can put a comment almost anywhere inside your HTML file: before a tag, after a tag, or even inside the <head> or <body> section. Here are a few real examples:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Page</title>
  <!-- Link the stylesheet here -->
  <link rel="stylesheet" href="style.css">
</head>
<body>

  <!-- Main navigation section -->
  <nav>
    <a href="index.html">Home</a>
    <a href="about.html">About</a>
  </nav>

  <!-- Hero section starts here -->
  <section class="hero">
    <h1>Welcome to My Website</h1>
  </section>
  <!-- Hero section ends here -->

</body>
</html>

Notice how the comments label each section of the page. When you come back to this file later, you immediately know what each block is doing. That is exactly why you add comments in HTML throughout your code.

If you are still getting comfortable with HTML page structure, check out our article on Building the Perfect HTML Document Structure first.

03Single Line vs HTML Multiline Comments

There are two main ways you will use this feature every day: a single comment line in HTML, or HTML multiline comments that span across several lines.

Single Comment Line in HTML

A single comment line in HTML is short and fits on one line. Use it when your note is brief and does not need much space.

<!-- Navigation bar -->
<nav>...</nav>

<!-- Footer section -->
<footer>...</footer>

<!-- TODO: Add a newsletter form here -->

Each of these is a single comment line in HTML. Quick, clean, and to the point. You will use these the most often.

HTML Multiline Comments

HTML multiline comments use the exact same  markers, but the content inside stretches across multiple lines. There is no special syntax for them. You just add line breaks inside.

<!--
  This is the product card section.
  Each card shows the product image, name, price, and a buy button.
  This section is dynamically populated with JavaScript.
  Last updated: March 2025
-->
<section class="products">
  ...
</section>

HTML multiline comments are perfect when you need to explain something in detail, write a longer note, or document a complex section of your page. They are also great for temporarily blocking out a large chunk of code during debugging, which we will cover below.

Single Line vs Multiline at a Glance

Single Comment Line in HTML

<!-- Navigation -->
<nav>...</nav>

Short, one-line notes. Best for labeling sections and quick reminders.

HTML Multiline Comments

<!--
  Product section.
  Uses JS to load.
  Updated: 2025
-->

Longer explanations. Spans multiple lines. Exact same syntax, just with line breaks.

04Why Comments in HTML Matter More Than You Think

A lot of beginners skip comments in HTML entirely. They think “I wrote this code, I will remember what it does.” That feeling disappears fast, especially as your projects grow.

Here is what happens without comments:

You revisit old code and spend 20 minutes figuring out what a section does.
A teammate opens your file and has no idea where anything is.
A bug appears and you cannot isolate which block is causing it.

Here is what happens with good use of comments in HTML:

You scan the file and instantly know where every section is.
Your teammate opens the file and understands the structure in seconds.
You comment out HTML blocks one by one to find the bug quickly.

Think of comments in HTML as small signs posted around a construction site. Every sign tells workers what that area is and what is happening there. Without signs, everyone is confused. With signs, work moves fast and nothing breaks accidentally.

Real Impact: Without vs With Comments

Without Comments

<div class="w1">
  <div class="c1"></div>
  <div class="c2"></div>
</div>
<div class="w2">
  <ul>...</ul>
</div>

What is w1? What is c2? Nobody knows without digging through the CSS.

With Comments

<!-- Hero Section -->
<div class="w1">
  <!-- Headline -->
  <div class="c1"></div>
  <!-- CTA Button -->
  <div class="c2"></div>
</div>
<!-- Navigation Links -->

Crystal clear. No guessing. Any developer knows exactly what each block is.

05How to Comment Out HTML (Temporarily Disable Code)

One of the most practical uses of the comment syntax is to comment out HTML that you do not want to delete but do not want to show right now. This is a technique every developer uses constantly.

When you comment out HTML, you wrap the code inside . The browser skips it entirely. Nothing changes on your page visually. But the code is still there, safe, waiting for you to un-comment it whenever you need it.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Comment Out Example</title>
</head>
<body>

  <h1>My Portfolio</h1>

  <!-- Hiding this section until the design is ready -->
  <!--
  <section class="projects">
    <h2>My Projects</h2>
    <p>Coming soon...</p>
  </section>
  -->

  <p>This paragraph is visible.</p>

</body>
</html>

In the example above, the entire projects section is commented out. It is not visible on the page. But when the design is ready, you just remove the  markers and the section appears instantly.

This is the cleanest way to comment out HTML temporarily. Never delete code you might need again. Comment it out instead.

Real Scenario: Switching Between Two Layouts

Here is a real-world case. You are testing two different header designs and want to quickly switch between them to see which one looks better:

<!-- Layout Option A (currently active) -->
<header class="header-centered">
  <h1>Welcome</h1>
  <p>Tagline goes here</p>
</header>

<!--
Layout Option B (testing this later)
<header class="header-left">
  <img src="logo.png" alt="Logo">
  <nav>...</nav>
</header>
-->

You just flip which one is commented and which one is not. No deleting. No retyping. No Ctrl+Z panic. This is one of the biggest reasons developers learn to properly comment out HTML as early as possible in their career.

06Using Comments for Debugging Like a Pro

Debugging HTML can be frustrating. Something looks broken, but you do not know which part is causing it. The fastest technique is to comment out HTML blocks one at a time until the problem disappears. When it does, you know exactly where the bug is.

This approach is called comment-based isolation and it works every single time.

Debugging Workflow with HTML Comments

Something is broken on your page. You do not know which section is responsible.

Comment out HTML block #1 using . Refresh the browser.

Problem still there? Un-comment block #1 and comment out block #2. Repeat.

Problem disappears after commenting a block? You found the culprit. Fix only that section.

Here is what this looks like in a real file:

<body>

  <header>...</header>

  <!--
  Testing: Is this banner section causing the layout overflow?
  <section class="banner">
    <div class="wide-block"></div>
  </section>
  -->

  <main>...</main>

  <footer>...</footer>

</body>

By choosing to comment out HTML in the banner section temporarily, you can check if it is the one breaking your layout. This is far faster than deleting code, undoing changes, or staring at the screen hoping to spot the issue. Good use of comments in HTML makes you a much faster and more confident debugger.

07Best Practices for Adding Comments in HTML

Knowing how to add comments in HTML is easy. Knowing when and how to use them well is a skill you develop over time. Here are the best practices every developer should follow.

1. Label the Start and End of Large Sections

When your HTML file grows large, it gets hard to tell where one section ends and another begins. Adding a comment line in HTML at the start and end of each section makes navigation instant.

<!-- ===== HERO SECTION START ===== -->
<section class="hero">
  <h1>Hello World</h1>
</section>
<!-- ===== HERO SECTION END ===== -->

<!-- ===== FEATURES SECTION START ===== -->
<section class="features">
  ...
</section>
<!-- ===== FEATURES SECTION END ===== -->

This is especially useful in long HTML files. You can scroll through and instantly spot every major section without having to read the code carefully.

2. Use Comments as TODO Notes

When you are building fast and want to come back to something later, leave a comment line in HTML marked as TODO. It is a simple habit that saves you from forgetting important tasks.

<!-- TODO: Replace this placeholder image with the real product photo -->
<img src="placeholder.jpg" alt="Product image">

<!-- TODO: Add the contact form once the backend is ready -->

<!-- TODO: Update this link after the new page is published -->
<a href="#">Read More</a>

3. Do Not Explain the Obvious

There is such a thing as too many comments in HTML. Do not write a comment explaining something that is already obvious from the tag itself. It just makes the file noisier and harder to read.

Helpful vs Unhelpful: Adding Comments in HTML

✗

Unhelpful: States the Obvious

<!-- This is a paragraph -->
<p>Hello World</p>

<!-- This is a heading -->
<h1>My Title</h1>

<!-- This is a link -->
<a href="about.html">About</a>

These add zero value. The tags already describe themselves perfectly.

✓

Helpful: Explains the “Why”

<!-- Fallback for users with no JS -->
<p class="no-js-msg">Enable JS.</p>

<!-- Critical: Do not change this ID,
     used by the analytics script -->
<div id="track-main"></div>

These explain the “why”, which the code itself can never tell you.

4. Always Explain the “Why”, Not Just the “What”

The code itself shows what it is doing. A good comment line in HTML should explain why. Why is this class here? Why is this section commented out? Why does this element have a specific ID? That context is what makes comments in HTML genuinely useful rather than just visual clutter.

5. Keep Comments Updated

Old comments that no longer match the code are worse than no comments at all. Every time you change a section, update the related comments in HTML as well. An outdated comment misleads you and your team into thinking the code does something it no longer does.

08Documenting Complex Code Sections with HTML Multiline Comments

Some parts of your HTML are more complex than others. Maybe a section has a very specific structure because of a CSS layout requirement. Maybe a form has unusual attributes for a third-party integration. These are the places where detailed html multiline comments are worth their weight in gold.

<!--
  PRICING TABLE SECTION
  =====================
  This section uses a CSS Grid layout.
  The grid changes from 1 column on mobile to 3 columns on desktop.
  The "featured" card uses the .card--highlight class to stand out visually.
  Do NOT remove the data-plan attributes -- they are required by the checkout JS.
-->
<section class="pricing">
  <div class="card" data-plan="basic">...</div>
  <div class="card card--highlight" data-plan="pro">...</div>
  <div class="card" data-plan="enterprise">...</div>
</section>

This kind of html multiline comment block turns your file into self-documenting code. The next developer who opens this file will know exactly what the section does, how it is structured, and what they should be careful about. They will not need to ask you anything, and they will not accidentally break a critical attribute.

Think of these detailed html multiline comments as a mini README embedded directly in your HTML. Complex forms, third-party widgets, accessibility-sensitive sections, and layout-critical blocks all deserve this treatment.

Documenting Accessibility Decisions

If you have read our guide on What Is Semantic HTML and Why It’s Your Secret Weapon, you know how much intentional decision-making goes into well-written HTML. A good comment line in HTML can document those decisions too, preventing a well-meaning future developer from accidentally undoing them:

<!--
  Using <button> here instead of <div> for keyboard accessibility.
  Screen readers will announce this as a button automatically.
  The aria-label is needed because the button contains only an icon with no visible text.
-->
<button aria-label="Close menu">
  <img src="close-icon.svg" alt="">
</button>

That comment prevents a future developer from changing your semantic <button> to a <div> without realizing the accessibility impact. Small note, big consequence avoided.

09Team Collaboration Through Comments in HTML

On team projects, comments in HTML become a form of communication. When multiple developers work on the same files, comments make the difference between a clean handoff and a confusing mess.

Marking Work in Progress

<!-- 
  WIP: Sara is currently rebuilding this section.
  Please do not edit below this line until April 10th.
-->
<section class="testimonials">
  ...
</section>
<!-- END WIP -->

Explaining Non-Obvious Decisions

<!-- 
  The empty div below is intentional.
  It acts as a CSS anchor target for smooth scrolling.
  Removing it will break the "Back to top" button behavior.
-->
<div id="top"></div>

Documenting Script Dependencies

<!-- 
  This slider requires slick.js to be loaded.
  See the bottom of this file for the script tag.
  Without it, the carousel will NOT initialize.
-->
<div class="slideshow">
  <div>Slide 1</div>
  <div>Slide 2</div>
  <div>Slide 3</div>
</div>

Every one of these saves someone hours of confusion. When you add comments in HTML with your team in mind, you are not just writing notes. You are writing documentation that lives right inside the file, always visible, always current.

Comment Tags Your Team Will Love

TODO:

A task that still needs to be done.

FIXME:

Known bug or broken section that needs attention.

NOTE:

Important context the next developer needs to know.

HACK:

A temporary workaround. Explains why so it can be fixed properly later.

WIP:

Work in progress. Do not touch until marked complete.

WARNING:

Critical info. Changing this may break something elsewhere.

10HTML Comments and SEO: What You Should Know

A common question beginners ask is whether comments in HTML affect SEO. The short answer is no, they do not directly impact your search rankings. Search engine crawlers parse HTML but typically ignore comment content when indexing your page text.

However, two things are worth knowing.

First, never put sensitive information inside comments in HTML on a live website. Even though the browser does not display them, anyone can view your page’s source code and read every single comment. Passwords, API keys, and private business notes do not belong there.

Second, while using a comment line in HTML here and there has no performance cost, embedding massive blocks of commented-out code on a production site unnecessarily increases file size. Keep your live files clean. Use comments generously during development, and remove the ones that are no longer relevant before publishing.

11Common Mistakes Beginners Make with HTML Comments

Mistake 1: Trying to Nest Comments

You cannot nest comments in HTML inside other comments. The browser sees the first --> it finds and closes the comment there, regardless of whether you intended it to or not. Everything after that gets rendered as regular broken code.

<!-- WRONG: attempting to nest one comment inside another
  <!-- This inner comment will cause problems -->
-->

<!-- CORRECT: Just one comment block at a time -->

Mistake 2: Forgetting the Closing Marker

If you open with , the browser treats everything after it as part of the comment. Large portions of your page disappear. This is especially common with html multiline comments that span many lines.

<!-- This comment is never closed...

<p>This paragraph is now INVISIBLE because it is still inside the comment.</p>
<footer>This footer is also hidden from the page!</footer>

--> <!-- The comment finally closes here -->

Mistake 3: Putting Sensitive Data in Comments

As covered earlier: never store passwords, keys, or confidential notes inside comments in HTML on a public site. Your source code is public. Comments in your HTML are not private.

Quick Syntax Check

The golden rule for all comments in HTML:

    <!–

    your comment text

    –>

✓
Always close with -->

✓
Works on single or multiple lines

✗
Never nest comments inside each other

✗
Never put private data in public HTML comments

12A Complete Commented HTML Page: Everything Put Together

Here is a complete, real-world HTML page using every technique from this tutorial. Notice how easy it is to read through and understand the structure, even without knowing anything about the project.

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Portfolio</title>

  <!-- Main stylesheet -->
  <link rel="stylesheet" href="style.css">

  <!--
    NOTE: The Google Fonts link loads two fonts.
    Removing it will cause fallback system fonts to be used instead.
  -->
  <link href="https://fonts.googleapis.com/css2?family=Inter&display=swap" rel="stylesheet">
</head>

<body>

  <!-- ===== HEADER START ===== -->
  <header>
    <!-- Logo links back to homepage -->
    <a href="index.html">
      <img src="logo.svg" alt="My Portfolio Logo">
    </a>

    <!-- TODO: Replace nav links once all pages are created -->
    <nav>
      <a href="index.html">Home</a>
      <a href="work.html">Work</a>
      <a href="contact.html">Contact</a>
    </nav>
  </header>
  <!-- ===== HEADER END ===== -->


  <!-- ===== HERO SECTION START ===== -->
  <section class="hero">
    <h1>Hi, I am Alex.</h1>
    <p>Front-end developer based in New York.</p>

    <!--
      WARNING: The button below has an ID used by the analytics script.
      Do not change or remove the id="cta-hero" attribute.
    -->
    <a href="work.html" id="cta-hero" class="btn">See My Work</a>
  </section>
  <!-- ===== HERO SECTION END ===== -->


  <!-- ===== PROJECTS SECTION START ===== -->
  <!--
    PROJECTS SECTION
    ================
    Currently hidden until project pages are built.
    Un-comment this block to make it visible on the page.
  -->
  <!--
  <section class="projects">
    <h2>My Projects</h2>
    <div class="grid">
      <div class="card">Project 1</div>
      <div class="card">Project 2</div>
    </div>
  </section>
  -->
  <!-- ===== PROJECTS SECTION END ===== -->


  <!-- ===== FOOTER START ===== -->
  <footer>
    <!-- FIXME: Copyright year should update dynamically. Currently hardcoded. -->
    <p>&copy; 2025 Alex. All rights reserved.</p>
  </footer>
  <!-- ===== FOOTER END ===== -->


  <!-- Scripts at end of body for better page load performance -->
  <script src="main.js"></script>

</body>
</html>

You can scan this file from top to bottom and instantly understand its structure. You know which sections are visible, which ones are temporarily commented out, what needs to be fixed, and what you should not touch. That is exactly the kind of code that a team, or your future self, will be grateful for.

If you want to deepen your understanding of how an HTML document is structured, our article on Building the Perfect HTML Document Structure is the perfect next read. And if you built your very first page following our Your First HTML Web Page tutorial, now is a great time to revisit it and add comments in HTML throughout the file.

13Quick Reference Cheat Sheet: Comments in HTML

HTML Comments Cheat Sheet

Single Comment Line in HTML

<!-- Short note here -->

Best for labeling sections, quick notes, and TODO items.

HTML Multiline Comments

<!--
  Line one.
  Line two.
  Line three.
-->

Best for documentation, complex explanations, and warning notes for your team.

Comment Out HTML

<!--
<section class="hidden">
  ...
</section>
-->

Best for temporarily hiding code, debugging issues, and testing layout changes.

Section Labels

<!-- HERO START -->
...
<!-- HERO END -->

Best for large HTML files, team projects, and complex page structures.

14You Now Know How to Use Comments in HTML

Comments are small additions to your code, but their impact is massive. A well-commented HTML file is easier to read, faster to debug, cleaner to hand off to a teammate, and far easier to revisit after time away.

Here is a quick recap of everything you learned today:

The syntax for comments in HTML is always  to close. Use a single comment line in HTML for short labels and quick notes. Use html multiline comments when your explanation needs multiple lines. Know how to comment out HTML to safely hide code temporarily or isolate bugs. Focus your comments on explaining the “why”. Keep them accurate. And use them generously, but not for things that are already obvious.

The next step in your HTML journey is learning how all these pieces fit into a complete, modern webpage. Explore our guide on What Is HTML5 to see how modern HTML has evolved, or revisit What Are HTML Tags, Elements, and Attributes to strengthen the foundation you are building on.

Start adding comments to your code today. Your future self and your teammates will thank you for it.

Comments in HTML

Choose a difficulty to load your challenge

Loading challenge…

Ready to Practice?

Select a difficulty level above to load your challenge.

Easy

Great Work!