HTML Comments: Documenting Your Code

Learning HTML is exciting, but it can also feel confusing when you come back to your code days or weeks later. What did you mean to do here? Why is this section important?

That’s where HTML comments come in. In this article, you’ll learn what HTML comments are, how to write them, and how to use them to keep your code clear and organized—even if you’re a complete beginner.

What Is an HTML Comment?

An HTML comment is a note you write inside your HTML file that browsers ignore. That means visitors to your website never see it, but you and other developers do when looking at the code.

HTML comments look like this:

<!-- This is a comment -->

Anything between  is treated as a comment.

You can use comments to:

Explain what a piece of code does
Leave reminders for yourself
Temporarily hide (or “comment out”) code while testing
Organize sections of your page

Basic HTML Comment Syntax

Let’s start with a very simple example.

<!DOCTYPE html>
<html>
<head>
  <title>My First Page</title>
</head>
<body>
  <!-- This is a comment explaining the heading below -->
  <h1>Welcome to My Page</h1>

  <!-- This paragraph introduces the page -->
  <p>This is my first HTML page. I'm learning how to write comments!</p>
</body>
</html>

What’s happening here?

 is a comment.
The browser does not show the comment on the page.
Only the <h1> heading and the <p> paragraph appear in the browser.

Expected result

On your web page, you will see:

Welcome to My Page (as a big heading)
This is my first HTML page. I'm learning how to write comments! (as normal text)

You will not see the comments, but you will see them in your code editor.

Writing Your First Comment (Step-by-Step)

Follow these steps to try it yourself.

Create a new file on your computer called comments-example.html.
Open it in a text editor (VS Code, Notepad, Sublime Text, etc.).
Paste this code into the file:

<!DOCTYPE html>
<html>
<head>
  <title>Comments Practice</title>
</head>
<body>
  <!-- Main title for the page -->
  <h1>My Practice Page</h1>

  <!-- Short description about this page -->
  <p>I'm practicing HTML comments. This text will show up on the page.</p>

  <!-- This text is only in the code. It will not appear in the browser. -->
</body>
</html>

Save the file.
Open it in your browser by double-clicking it.

You’ll see the heading and paragraph, but not the comments.

Using Comments to Organize Sections

As your pages grow, you’ll have more and more HTML. Comments can help you label sections so you don’t get lost.

Here’s an example of a slightly larger page with section comments:

<!DOCTYPE html>
<html>
<head>
  <title>My Simple Website</title>
</head>
<body>
  <!-- ===== Header Section ===== -->
  <header>
    <h1>My Simple Website</h1>
    <p>Learning HTML, one step at a time.</p>
  </header>

  <!-- ===== About Section ===== -->
  <section>
    <h2>About Me</h2>
    <p>I am learning how to make websites and document my code.</p>
  </section>

  <!-- ===== Footer Section ===== -->
  <footer>
    <p>&copy; 2025 My Simple Website</p>
  </footer>
</body>
</html>

Why this is useful

The comments like  act like labels.
When you scroll through the code, you can quickly see where each section begins.
This becomes very helpful when your file has dozens or hundreds of lines.

Try it yourself:

Open your comments-example.html file and:

Add a comment above your <h1> to label it as the Header.
Add another comment above a new <section> you create, for example, .

You’re now using comments to organize your page like a pro.

Using Comments to Explain Code

Comments are also great for explaining why you wrote something a certain way.

Imagine you have a list of your favorite hobbies:

<!DOCTYPE html>
<html>
<head>
  <title>My Hobbies</title>
</head>
<body>
  <!-- Main heading of the page -->
  <h1>My Hobbies</h1>

  <!-- I used an unordered list because the order doesn't matter -->
  <ul>
    <li>Reading</li>
    <li>Drawing</li>
    <li>Cycling</li>
  </ul>
</body>
</html>

Explanation

The comment above the <h1> tells anyone reading the code what that heading is for.
The comment above the <ul> (unordered list) explains why you chose that tag.

This might seem obvious now, but when your code gets more complex, these notes can save you a lot of time.

Try it yourself:

Add a list of your three favorite foods.
Above the list, add a comment explaining what the list is, like:

<!-- List of my favorite foods -->

You’re learning to document your decisions, not just your code.

Commenting Out Code (Temporarily Disabling It)

Sometimes, you want to hide part of your page without deleting it. Comments let you “turn off” code temporarily.

Look at this example:

<!DOCTYPE html>
<html>
<head>
  <title>Testing Comments</title>
</head>
<body>
  <h1>Welcome!</h1>

  <!--
  <p>This paragraph is hidden for now. I'm testing what the page looks like without it.</p>
  -->

  <p>This paragraph is still visible.</p>
</body>
</html>

What’s happening?

The second paragraph is inside a comment block.
The browser ignores everything between .
Only the heading and the last paragraph show up on the page.

This is called commenting out code.

It’s helpful when:

You want to test how the page looks without a certain element
You’re trying to find what’s causing a problem
You’re not ready to delete something yet, but you don’t want it visible

Try it yourself:

Take any paragraph or heading in your file.
Wrap it with  on separate lines.
Refresh your browser and see it disappear.

To bring it back, simply remove the comment marks.

Multi-Line Comments

Comments don’t have to be on a single line. You can write longer notes across multiple lines.

<!--
This is a longer comment.
I can explain multiple things here:
1. What this section does
2. Why I wrote it this way
3. What I might change later
-->

Use multi-line comments when you need more detail, but try to keep them clear and focused.

Common Mistakes to Avoid

Here are a few things beginners often get wrong with HTML comments:

Forgetting to close the comment
You must always close comments with -->. If you don’t, the browser may think the rest of your page is a comment!
Putting -- inside a comment
Avoid writing -- inside your comments. It can confuse the browser.
Trying to nest comments
HTML doesn’t support comments inside comments. This can break your page.

Example of a broken comment (don’t do this):

<!--
  <p>This is a comment <!-- and another comment inside --></p>
-->

Stick to simple, clear comments, and you’ll be fine.

Practice Idea: Build a Commented Mini Page

Now that you know how to use comments, try building a small page and document every section.

Here’s a mini template to get you started:

<!DOCTYPE html>
<html>
<head>
  <title>My Profile Page</title>
</head>
<body>
  <!-- Header: Page title and introduction -->
  <header>
    <h1>Hi, I'm [Your Name]</h1>
    <p>Welcome to my simple profile page.</p>
  </header>

  <!-- About Me section -->
  <section>
    <h2>About Me</h2>
    <p>Write a few sentences about yourself here.</p>
  </section>

  <!-- Favorite Things section -->
  <section>
    <h2>My Favorite Things</h2>
    <!-- List of favorite things -->
    <ul>
      <li>Favorite food</li>
      <li>Favorite hobby</li>
      <li>Favorite place</li>
    </ul>
  </section>

  <!-- Footer with a small note -->
  <footer>
    <p>Thanks for visiting my page!</p>
  </footer>
</body>
</html>

Try it yourself:

Replace [Your Name] and the placeholder text with your own details.
Add at least three new comments explaining different parts of your page.
Open it in your browser and admire your documented code.

You’ve just created a small, well-commented web page. That’s a big step.

Quick Recap and What’s Next

Here’s what you learned about HTML comments:

HTML comments use  to end.
Comments are not shown in the browser; they’re only visible in the code.
You can use comments to label sections, explain code, and temporarily hide elements.
Clear comments make your code easier to read, understand, and update later.

As you continue learning HTML and CSS, keep using comments to document your work. Your future self—and anyone else who reads your code—will be grateful.

Next steps:

Practice adding comments to every new HTML file you create.
Start learning about basic HTML structure (headings, paragraphs, lists) and use comments to describe each part.

You’re doing the right thing by building good habits early. Keep going—every comment you write is one more step toward becoming a confident web developer.

Mudzinga

HTML Comments: Documenting Your Code

What Is an HTML Comment?

Basic HTML Comment Syntax

What’s happening here?

Expected result

Writing Your First Comment (Step-by-Step)

Using Comments to Organize Sections

Why this is useful

Using Comments to Explain Code

Explanation

Commenting Out Code (Temporarily Disabling It)

What’s happening?

Multi-Line Comments

Common Mistakes to Avoid

Practice Idea: Build a Commented Mini Page

Quick Recap and What’s Next

About Percy Mudzinga

Related Articles

HTML Comments: Documenting Your Code

What Is an HTML Comment?

Basic HTML Comment Syntax

What’s happening here?

Expected result

Writing Your First Comment (Step-by-Step)

Using Comments to Organize Sections

Why this is useful

Using Comments to Explain Code

Explanation

Commenting Out Code (Temporarily Disabling It)

What’s happening?

Multi-Line Comments

Common Mistakes to Avoid

Practice Idea: Build a Commented Mini Page

Quick Recap and What’s Next

About Percy Mudzinga

Related Articles

Never Miss an Update