Home / Learn / HTML / Comments in Code

The Quick Start

Comments in Code

Written by Fahim ul Haq

Fahim ul Haq is the co-founder and CEO of Educative, the world's leading upskilling platform for and by developers. He is a former software engineer at Microsoft and Facebook with a deep passion for creating better, more efficient ways for developers to master in-demand skills.

When you’re learning HTML, it’s easy to focus only on what appears in the browser. But behind every clean, understandable web page is code that is easy for humans to read and maintain. One of the most important tools for writing readable code is comments.

In this lesson, you’ll learn what comments are, why they matter, and how to use them correctly in HTML. You’ll see how comments help explain code, prevent confusion, and make collaboration easier. You’ll also practice writing comments step by step so they become a natural part of how you write HTML.

By the end of this lesson, you’ll understand that comments are not just for advanced developers. They are a beginner-friendly habit that improves your code from day one.

What are comments?

Comments are notes written inside your code that are meant for humans, not browsers. When a browser reads an HTML file, it completely ignores comments.

This means comments do not affect how the page looks or behaves. They exist only to help you and other developers understand the code.

Comments are often used to explain what a section of code does, why a certain choice was made, or to temporarily disable part of the code during testing.

Why comments matter in HTML

Even simple HTML files can become confusing over time. As your pages grow, you may forget why certain elements exist or what a section is meant to do.

Comments help solve this problem. They act like short explanations placed directly next to the code they describe. When used correctly, comments make your HTML easier to read, debug, and update later.

Comments are especially useful when:

Learning new concepts
Revisiting old projects
Sharing code with others
Organizing large pages

Building the habit of commenting early will save you time and frustration later.

How comments work in HTML

HTML comments use a specific syntax. They start with .

Anything written between these markers is treated as a comment.

Here is a simple example:

				
					<!-- This is a comment -->

The browser ignores this line completely. It will not appear on the page, and it will not affect layout or content.

Adding your first comment

Let’s add a comment to a basic HTML page.

Start with this simple structure:

				
					<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Comments in HTML</title>
  </head>
  <body>
    <h1>Learning HTML</h1>
    <p>This page demonstrates HTML comments.</p>
  </body>
</html>

Now add a comment above the heading:

				
					<!-- Main page heading -->
<h1>Learning HTML</h1>

Save the file and open it in your browser. You will not see the comment anywhere on the page. That’s expected. Comments exist only in the code.

Comments vs visible text

It’s important to understand the difference between comments and content.

Text inside HTML elements, such as paragraphs and headings, appears on the page. Comments never do.

For example:

				
					<p>This text appears on the page.</p>
<!-- This text does not appear on the page -->

This distinction is what makes comments useful. They allow you to explain your code without changing what users see.

Using comments to explain structure

One of the best uses of comments is explaining the structure of a page.

As your HTML grows, you may have multiple sections, such as headers, main content, and footers. Comments help separate these sections clearly.

Example:

				
					<!-- Header section -->
<h1>My Website</h1>

<!-- Main content -->
<p>Welcome to my website.</p>

<!-- Footer -->
<p>Copyright 2025</p>

Even in a simple page, comments make the layout easier to understand at a glance.

Step-by-step: commenting a basic page

Let’s practice adding comments to a full HTML document.

Start with this page:

				
					<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Comment Practice</title>
  </head>
  <body>
    <h1>My Learning Journey</h1>
    <p>I am learning HTML step by step.</p>

    <h2>Goals</h2>
    <p>Understand the basics of web development.</p>
  </body>
</html>

Now add comments to explain each section:

				
					<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- Metadata for the page -->
    <meta charset="UTF-8" />
    <title>Comment Practice</title>
  </head>
  <body>
    <!-- Main heading -->
    <h1>My Learning Journey</h1>

    <!-- Introduction paragraph -->
    <p>I am learning HTML step by step.</p>

    <!-- Goals section -->
    <h2>Goals</h2>
    <p>Understand the basics of web development.</p>
  </body>
</html>

The page looks exactly the same in the browser, but the code is now much easier to read.

Comments for learning and reminders

When you’re new to HTML, comments are a great way to leave reminders for yourself.

You might comment on:

What a tag does
Why you chose a certain structure
What you plan to add later

Example:

				
					<!-- TODO: Add a navigation menu here -->

These notes help guide your learning and remind you what to work on next.

Temporarily disabling code with comments

Another useful feature of comments is the ability to temporarily disable code.

If you wrap an HTML element in comment markers, the browser ignores it.

Example:

				
					<!--
<p>This paragraph is hidden for now.</p>
-->

This is helpful when testing layouts or experimenting without deleting code permanently.

Be careful when commenting out large sections, though. Nested comments are not allowed in HTML and can cause issues if done incorrectly.

Comments do not nest in HTML

HTML comments cannot be nested inside other comments. This means you cannot put one comment inside another.

Example of what not to do:

				
					<!--
  This is a comment
  <!-- Nested comment -->
-->

This can break your HTML. Always make sure each comment has a clear start and end.

Writing good comments

Good comments are clear, short, and useful. They explain why something exists, not just what it is.

For example, this comment isn’t very helpful:

				
					<!-- Paragraph -->
<p>Welcome to the site.</p>

A better comment would be:

				
					<!-- Introductory message for new visitors -->
<p>Welcome to the site.</p>

Aim to write comments that add value rather than repeat the obvious.

Avoid over-commenting

While comments are helpful, too many comments can clutter your code.

If your HTML is simple and clear, you may not need a comment for every line. Focus on commenting sections, complex parts, or anything that might be confusing later.

As you gain experience, you’ll naturally learn when comments are necessary and when they’re not.

Comments and collaboration

In real-world projects, HTML is often written by teams. Comments help teammates understand your intentions without needing extra explanations.

Clear comments:

Reduce misunderstandings
Make onboarding easier for new developers
Improve long-term maintainability

Even when working alone, future-you counts as a teammate. Comments help you remember what you were thinking when you wrote the code.

Viewing comments in the browser

Although comments do not appear on the page, they are still visible in the page source.

If you right-click on a page and choose “View Page Source,” you’ll see the HTML, including comments.

This is another reason to avoid putting sensitive information inside comments. Anyone can see them by viewing the source.

What not to put in comments

Never put sensitive data in comments, such as:

Passwords
API keys
Private URLs
Personal information

Comments are ignored by the browser but not hidden from users.

Step-by-step: commenting a real page

Let’s create a small, well-commented HTML page.

				
					<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- Page metadata -->
    <meta charset="UTF-8" />
    <title>Commented Page</title>
  </head>
  <body>
    <!-- Site title -->
    <h1>Welcome</h1>

    <!-- Intro text -->
    <p>
      This page demonstrates how comments can make HTML easier to understand.
    </p>

    <!-- Learning section -->
    <h2>What I’m Learning</h2>
    <p>
      I’m learning how to write clean, readable HTML using comments and structure.
    </p>

    <!-- Footer note -->
    <p>
      <small>Last updated in 2025</small>
    </p>
  </body>
</html>

This page works exactly like any other HTML page, but the comments make its purpose and structure clear.

Common beginner mistakes with comments

One common mistake is forgetting to close a comment. This can cause large sections of HTML to disappear unexpectedly.

Another mistake is using comments instead of removing unused code permanently. Comments are helpful, but they shouldn’t replace proper cleanup.

Always double-check that each .

How comments fit into good HTML habits

Comments are part of writing professional, maintainable code. They don’t replace good structure, but they support it.

Well-structured HTML with thoughtful comments is easier to style, script, and expand later.

Learning this habit early puts you ahead of many beginners who skip commenting entirely.

What you should understand after this lesson

By now, you should be comfortable with:

Writing HTML comments correctly
Understanding that comments are ignored by browsers
Using comments to explain structure and intent
Temporarily disabling code with comments
Avoiding common comment mistakes

You don’t need to comment every line. Focus on clarity and usefulness.

What’s next?

Now that you know how to write and use comments, you’re ready to move on to grouping and organizing content more effectively.

In the next lesson, you’ll learn about semantic HTML elements and how they help create meaningful, accessible page layouts.

Before moving on, try adding comments to one of your earlier HTML practice files. Explaining your own code is one of the best ways to reinforce what you’ve learned.

On this page

In This Module

1. The Quick Start