HTML Comments

Learn how to use HTML comments to document code, organize sections, explain important decisions, and temporarily disable HTML elements without displaying them on the webpage.

Introduction

In the previous lesson, you learned about HTML Text Formatting and how different elements represent importance, emphasis, highlights, edits, and specialized text.

As HTML documents grow larger, developers may work with hundreds or thousands of lines of code. Without explanations or clear organization, it can become difficult to remember why certain code exists, where a section begins, or which code is temporarily under development.

HTML provides comments so developers can write notes directly inside an HTML document without displaying those notes as normal webpage content.

Comments can explain code, identify sections, leave maintenance notes, and temporarily prevent HTML code from appearing on the webpage.

Basic HTML Comment

<!-- Main page heading -->

<h1>Learn HTML</h1>

<!-- Introduction paragraph -->

<p>
    HTML is used to structure webpages.
</p>

Write HTML Code

↓

Add Developer Notes

↓

Wrap Notes in Comment Syntax

↓

Browser Reads the Document

↓

Comment is Not Rendered

↓

Visible Content is Displayed

Comments Are Part of the Source Code

HTML comments remain inside the HTML document, but they are not displayed as normal visible content on the webpage.

What are HTML Comments?

HTML comments are notes or blocks of content written inside an HTML document using special comment syntax.

They are primarily written for developers rather than website visitors.

Comments can explain the purpose of code, divide a large document into sections, leave useful maintenance information, or temporarily comment out HTML during development.

Comment with Visible Content

<!-- This note is not displayed -->

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

HTML Comment

Written for developers.
Remains in the source code.
Not displayed as normal page content.
Can explain or organize code.

HTML Content

Usually written for website users.
Becomes part of the webpage structure.
Can be displayed by the browser.
Communicates page content.

Documentation

Explain the purpose of important or unusual code.

Organization

Divide large HTML documents into recognizable sections.

Testing

Temporarily comment out HTML while investigating a problem.

Collaboration

Provide useful context for developers working on the same project.

Simple Definition

An HTML comment is a note or commented block inside an HTML document that is not displayed as normal webpage content.

Why Do We Need Comments?

Small HTML documents may be easy to understand without comments, but larger projects often contain many sections, components, repeated patterns, and temporary changes.

Useful comments provide context that may not be obvious from the HTML structure alone.

Without Useful Comments

Large files can be harder to navigate.
The reason for unusual code may be forgotten.
Temporary decisions may be unclear.
Team members may need more time to understand unfamiliar sections.
Debugging notes may be lost.

With Useful Comments

Important sections can be identified quickly.
Unusual decisions can be explained.
Temporary work can be documented.
Team members receive useful context.
Code can be commented out during testing.

Readability

Helpful comments can make complex or unusual sections easier to understand.

Organization

Section comments can make long HTML documents easier to navigate.

Teamwork

Developers can leave useful context for other contributors.

Debugging

HTML blocks can be temporarily commented out while testing.

Maintenance

Comments can explain temporary decisions or future work.

Context

Useful comments can explain why code exists when the reason is not obvious.

Identify Complex or Important Code

↓

Determine What Context is Missing

↓

Write a Concise Comment

↓

Place it Near the Relevant Code

↓

Help Future Developers Understand the Section

Not Every Line Needs a Comment

Comments are useful when they add context. Writing comments that only repeat obvious HTML can make a document more cluttered rather than easier to understand.

Real-World Analogy

Imagine reading a textbook, technical document, or set of construction plans.

The main content is intended for the reader, but additional notes may be written in margins or annotations to help editors and contributors understand important details.

HTML comments work in a similar way. The webpage content is intended for visitors, while comments provide notes inside the source code for developers.

Textbook and HTML Analogy

Textbook                    HTML Document
────────                    ─────────────

Book Content                Visible HTML Content
│                           │
├── Chapter                 ├── Heading
│                           │
├── Paragraph               ├── Paragraph
│                           │
└── Editor Note             └── HTML Comment
    Not part of main text        Not rendered as page content

Document Annotation

Provides notes for editors or contributors.
Adds context around the main content.
Can explain decisions or future changes.
Is separate from the main reading experience.

HTML Comment

Provides notes for developers.
Adds context around HTML code.
Can explain decisions or temporary work.
Is not displayed as normal webpage content.

Developer Notes Inside the Document

Comments allow developers to place useful notes near the exact HTML code those notes describe.

Comment Syntax

An HTML comment begins with .

The content between these comment markers is treated as comment content rather than normal visible webpage content.

HTML Comment Syntax

<!-- This is a comment -->

Comment Anatomy

<!-- This is a comment -->
──── ───────────────── ───
 │           │           │
 │           │           └── Closing Comment Marker
 │           │
 │           └── Comment Content
 │
 └── Opening Comment Marker

Part	Syntax	Purpose
Opening marker	<!--	Starts the HTML comment
Comment content	This is a comment	Contains the developer note or commented content
Closing marker	-->	Ends the HTML comment

Comment Before an Element

<!-- Main heading -->

<h1>Learn HTML</h1>

Remember Both Markers

Every HTML comment needs the correct opening marker .

Example 1: Simple Comment

A simple comment can provide a short note about nearby HTML code.

Simple Comment

<!-- This is a comment -->

<p>Hello World</p>

The comment remains in the HTML source code, while the paragraph is displayed as normal webpage content.

Simple Comment Example

Browser Reads Comment

↓

Comment is Not Painted as Page Content

↓

Browser Continues Parsing

↓

Paragraph is Processed

↓

Hello World is Displayed

Only Visible HTML Content Appears

The visitor sees the paragraph text. The comment does not appear as normal content on the rendered webpage.

Example 2: Commenting Out HTML Code

Comments can temporarily prevent a block of HTML from being rendered as normal webpage content.

This technique is commonly called commenting out code and can be useful during development, testing, and debugging.

Temporarily Disabled HTML

<h1>Welcome to HTML</h1>

<!--
<p>
    This paragraph is temporarily disabled.
</p>
-->

<p>HTML is easy to learn.</p>

Commented-Out Content

Welcome to HTML

Source Code

The heading remains active.
One paragraph is inside a comment.
The final paragraph remains active.
The disabled code is still present in the file.

Browser Output

The heading is displayed.
The commented paragraph is not displayed.
The final paragraph is displayed.
Only active content appears as normal page content.

Testing a Section

<!-- Original section temporarily disabled

<section>
    <h2>Special Offer</h2>
    <p>Offer ends today.</p>
</section>

-->

<section>
    <h2>New Offer</h2>
    <p>Offer ends this week.</p>
</section>

Useful During Temporary Testing

Commenting out code can help test whether a particular HTML block is related to a problem without immediately deleting that block.

Do Not Treat Comments as Permanent Version Control

For long-term history and previous versions of code, use a version control system. Large amounts of old commented-out code make HTML harder to maintain.

Example 3: Organizing HTML Code

Comments can identify major sections in a long HTML document.

This can make it easier for developers to scan the source code and quickly locate important areas.

Organizing Page Sections

<!-- Header Section -->

<header>
    <h1>PrograMinds</h1>
</header>


<!-- Main Content -->

<main>
    <p>Welcome to HTML.</p>
</main>


<!-- Footer Section -->

<footer>
    <p>Copyright 2026</p>
</footer>

Organized Document Structure

HTML Document
│
├── <!-- Header Section -->
│   └── <header>
│
├── <!-- Main Content -->
│   └── <main>
│
└── <!-- Footer Section -->
    └── <footer>

Header

A comment can identify where the header section begins.

Main Content

A comment can identify the primary page content.

Footer

A comment can identify the final footer section.

Navigation

Developers can search for section comments in large files.

Use Section Comments Consistently

If section comments are useful in a project, use a consistent naming pattern so developers can scan and search the document easily.

Multi-Line Comments

An HTML comment can contain content across multiple lines.

The opening comment marker appears before the comment content, and the closing marker appears after the final line.

Multi-Line Comment

<!--
    This webpage explains HTML comments.
    The lesson contains practical examples.
    Updated in 2026.
-->

Multi-Line Comment Structure

<!--
  │
  ├── First comment line
  ├── Second comment line
  ├── Third comment line
  │
-->

Longer Notes

Explain information that does not fit clearly on one short line.

Temporary Blocks

Temporarily comment out multiple lines of HTML.

Maintenance Information

Document temporary decisions or important implementation context.

Section Documentation

Provide context before a complex section of markup.

Commenting Out Multiple Elements

<!--
<h2>Temporary Section</h2>

<p>
    This section is currently disabled.
</p>

<a href="/offer">View Offer</a>
-->

Keep Long Comments Focused

A multi-line comment should still provide useful and concise context. Very long explanations may become difficult to maintain.

Browser Rendering Process

When a browser processes an HTML document, comments are recognized by the HTML parser as comments rather than normal visible elements.

Receive HTML Document

↓

Parse the Source

↓

Recognize Comment Syntax

↓

Create Comment Information in the Document Model

↓

Do Not Render Comment as Visible Content

↓

Continue Processing HTML

↓

Display the Webpage

Simplified Comment Processing

HTML Source
    │
    ▼
Read <!-- Comment -->
    │
    ▼
Recognize Comment Syntax
    │
    ▼
Do Not Create Visible Page Content
    │
    ▼
Continue Parsing HTML
    │
    ▼
Process Visible Elements
    │
    ▼
Display Webpage

Source Example

<!-- Navigation -->

<nav>
    <a href="/">Home</a>
</nav>

The navigation element can contribute visible and interactive content to the webpage. The preceding comment does not appear as normal rendered text.

Comments Are Not Visible Elements

Comments can exist in the parsed document, but they do not create visible boxes or text in the normal webpage layout.

Comments vs Visible Content

Comments and normal HTML elements serve different purposes inside an HTML document.

Feature	HTML Comments	Visible HTML Content
Primary audience	Developers	Website users
Normal page visibility	Not displayed	Can be displayed
Purpose	Notes, context, organization, temporary disabling	Page structure and content
Syntax example	<!-- Note -->	<p>Content</p>
Creates visible text	No	Can create visible text
Useful for documentation	Yes	Not its primary purpose

Comment

Provides developer-facing context.
Does not appear as normal visible page content.
Can identify sections.
Can temporarily contain disabled HTML.

Visible Content

Communicates information to users.
Can appear in the webpage layout.
Creates document structure.
Can be styled and interacted with.

Comment and Visible Content Together

<!-- Product description -->

<p>
    This product includes one year
    of technical support.
</p>

Visible Content Only

Different Audiences

The comment helps developers understand the source code, while the paragraph communicates information to website visitors.

Real-World Applications

HTML comments are useful in many development and maintenance situations when they provide meaningful context.

Large Websites

Identify major page sections and important structural boundaries.

Team Projects

Provide context about unusual code or temporary implementation decisions.

Website Maintenance

Leave concise notes about temporary work or future cleanup.

Debugging

Temporarily comment out HTML blocks while testing a problem.

Templates

Identify reusable or dynamically generated sections.

Experiments

Temporarily compare alternative markup structures.

Educational Code

Explain examples and identify important sections for learners.

Source Navigation

Make important sections easier to locate in long HTML files.

Advantages of Comments

Better Understanding

Useful comments can explain context that is not obvious from the code.

Better Organization

Section comments can divide long files into recognizable areas.

Easier Collaboration

Team members can understand important decisions more quickly.

Debugging Support

Code can be temporarily commented out while investigating problems.

Easier Maintenance

Important temporary information can remain close to the relevant code.

Faster Navigation

Developers can search for consistent section comments.

Preserved Context

Comments can explain why unusual code or workarounds exist.

Safe Temporary Testing

A block can be disabled temporarily without immediately deleting it.

Add developer-facing notes to HTML documents.
Explain unusual or complex code.
Document important implementation decisions.
Identify major sections in large files.
Make source code easier to navigate.
Help developers understand unfamiliar code.
Support team collaboration.
Provide temporary maintenance context.
Comment out HTML during testing.
Help isolate layout problems.
Preserve code temporarily during experiments.
Improve educational examples.
Make long templates easier to scan.
Provide context near the relevant code.
Improve maintainability when used carefully.

Common Beginner Mistakes

Forgetting the Closing Marker

Every comment needs the closing --> marker. An unclosed comment can cause later content to be treated unexpectedly.

Using Incorrect Comment Syntax

HTML comments use . Do not use JavaScript or CSS comment syntax in HTML.

Expecting Comments to Appear

Comments are not displayed as normal webpage content. Use HTML elements when visitors need to see information.

Storing Sensitive Information

Comments can be inspected in delivered source code. Never place passwords, secrets, private keys, or confidential information inside them.

Overusing Comments

Do not comment every obvious line. Too many unnecessary comments make code harder to scan.

Keeping Outdated Comments

A comment that no longer matches the code can mislead developers.

Leaving Large Blocks of Dead Code

Do not keep old commented-out code permanently. Use version control for historical code.

Explaining What Instead of Why

Comments are most useful when they explain important context or reasoning that the code itself does not show clearly.

Closing the Comment Correctly

<!-- ❌ Missing closing marker

<h1>Welcome</h1>


<!-- ✅ Correct comment -->

<!-- Main heading -->

<h1>Welcome</h1>

Use HTML Comment Syntax

<!-- ❌ JavaScript-style comment -->

// Navigation section


<!-- ❌ CSS-style comment -->

/* Navigation section */


<!-- ✅ HTML comment -->

<!-- Navigation section -->

Never Store Sensitive Information

<!-- ❌ Never place secrets in HTML comments -->

<!-- Password: example-password -->
<!-- Private API Key: secret-value -->


<!-- ✅ Keep sensitive data out of client-delivered HTML -->

<!-- Authentication handled securely on the server -->

Avoid Obvious Comments

<!-- ❌ Unnecessary comment -->

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


<!-- ✅ Useful context -->

<!-- Temporary notice shown during scheduled maintenance -->
<p>Service will return at 6:00 PM.</p>

Keep Comments Updated

<!-- ❌ Outdated comment -->

<!-- Footer Section -->
<header>
    <h1>PrograMinds</h1>
</header>


<!-- ✅ Accurate comment -->

<!-- Header Section -->
<header>
    <h1>PrograMinds</h1>
</header>

Poor Comments

Repeat obvious HTML.
Contain outdated information.
Store sensitive data.
Leave large amounts of dead code.
Add clutter without useful context.

Useful Comments

Explain important context.
Remain accurate and current.
Never contain secrets.
Stay concise and relevant.
Help developers understand the code.

Comments Are Not a Secure Storage Location

A comment may be hidden from the normal page display, but source code delivered to users can still be inspected. Never place sensitive information in HTML comments.

Best Practices

Write comments only when they add useful context.
Keep comments concise and easy to understand.
Explain why unusual code exists.
Use comments to identify important sections in long files.
Use consistent wording for section comments.
Place comments close to the code they describe.
Keep comments accurate when the code changes.
Remove outdated comments.
Avoid comments that simply repeat obvious HTML.
Never place passwords in comments.
Never place API secrets in comments.
Never place private keys or confidential information in comments.
Remember that delivered HTML source can be inspected.
Use comments temporarily while debugging.
Remove unnecessary commented-out code after testing.
Use version control instead of storing old code in comments.
Avoid large blocks of permanent dead code.
Use multi-line comments only when longer context is necessary.
Do not use comments as visible instructions for users.
Use actual HTML elements for user-facing information.
Review comments during code maintenance.
Update comments when implementation decisions change.
Prefer clear HTML structure over excessive explanatory comments.
Use comments to explain non-obvious decisions.
Keep project comment style consistent.

Professional Comment Usage

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

    <!-- Primary site navigation -->
    <header>
        <nav>
            <a href="/">Home</a>
            <a href="/learn">Learn</a>
        </nav>
    </header>

    <!-- Main lesson content -->
    <main>
        <article>
            <h1>HTML Comments</h1>

            <p>
                Comments provide developer-facing
                notes inside HTML documents.
            </p>
        </article>
    </main>

    <!-- Site-wide footer -->
    <footer>
        <p>Copyright 2026 PrograMinds</p>
    </footer>

</body>
</html>

Write Comments for Future Readers

A useful comment should help another developer understand important context without requiring them to guess why the comment exists.

Frequently Asked Questions

What is an HTML comment?

An HTML comment is a developer-facing note or commented block written inside an HTML document that is not displayed as normal webpage content.

What syntax is used for HTML comments?

An HTML comment starts with .

Are HTML comments displayed on the webpage?

No. HTML comments are not displayed as normal visible webpage content.

Can website visitors see HTML comments?

Comments are not shown in the normal page display, but comments included in HTML delivered to the browser may be visible when someone inspects the page source or developer tools.

Can HTML comments contain multiple lines?

Yes. Comment content can span multiple lines between the opening and closing comment markers.

Can HTML comments contain HTML code?

Comments can be used to temporarily comment out blocks of HTML so that the code is not rendered as normal webpage content.

What does commenting out code mean?

Commenting out code means temporarily placing code inside comment syntax so it does not behave as active visible HTML content.

Why do developers comment out HTML?

Developers may comment out HTML temporarily while debugging, testing alternatives, or investigating layout problems.

Should commented-out code remain permanently?

Usually not. Remove unnecessary dead code and use version control when you need access to previous versions.

Can comments organize large HTML files?

Yes. Concise section comments can identify areas such as navigation, main content, and footer sections.

Should every HTML element have a comment?

No. Comments should add useful context rather than repeat information that is already obvious from the HTML.

What happens if I forget the closing comment marker?

The browser may treat following content as part of the comment until it encounters a valid closing marker, which can prevent expected content from appearing.

Can I use // for HTML comments?

No. Double slashes are commonly associated with comments in languages such as JavaScript, but HTML comments use .

Can I use /* */ for HTML comments?

No. That syntax is used for CSS and some programming languages. HTML uses .

Can I store a password in an HTML comment?

No. Never store passwords, API secrets, private keys, or confidential information in HTML comments.

Why are secrets unsafe in comments?

HTML source delivered to a browser can be inspected, so hidden comments must never be treated as secure or private storage.

Can comments improve teamwork?

Yes. Useful comments can provide context about unusual decisions, temporary work, and important sections for other developers.

Can comments become harmful?

Yes. Outdated, excessive, misleading, or unnecessary comments can make code harder to maintain.

Should comments explain what the code does?

Sometimes, but comments are often most valuable when they explain important context or why a non-obvious decision was made.

Can CSS style an HTML comment?

No. HTML comments do not create normal visible elements that can be styled as page content.

Do comments create space on the webpage?

No. Comments do not create visible layout boxes or spacing in the normal webpage display.

Are comments useful for debugging?

Yes. Temporarily commenting out sections can help determine whether particular HTML blocks are related to a problem.

What should I use for code history instead of comments?

Use a version control system to track previous versions and changes over time.

What should I learn after HTML comments?

The next lesson is HTML Links, where you will learn how to create navigation between pages, websites, sections, and other resources.

Key Takeaways

HTML comments provide developer-facing notes inside HTML documents.
A comment begins with .
Comments are not displayed as normal visible webpage content.
Comments can explain important or unusual code.
Comments can identify sections in large HTML files.
Comments can help developers navigate source code.
Comments can provide useful context for team members.
HTML code can be temporarily commented out.
Commenting out code can help during testing and debugging.
Comments can span multiple lines.
Not every HTML element needs a comment.
Comments should add useful context.
Avoid comments that simply repeat obvious code.
Keep comments concise.
Keep comments accurate.
Remove outdated comments.
Do not leave large amounts of old commented-out code.
Use version control for code history.
Never store passwords in comments.
Never store API secrets in comments.
Never store private keys in comments.
Comments delivered to browsers may be inspected.
Comments do not create visible webpage spacing.
Comments are not a replacement for user-facing content.
Well-written comments can improve maintainability and collaboration.

Summary

HTML comments allow developers to place notes and commented content inside an HTML document without displaying them as normal webpage content.

A comment begins with the  closing marker.

Comments can explain non-obvious code, identify major sections, provide useful maintenance context, and temporarily comment out HTML during testing.

Comments can contain one line or multiple lines, but they should remain concise, accurate, and relevant to the code they describe.

Comments should not simply repeat obvious HTML, and outdated comments should be removed or updated because misleading documentation can make code harder to maintain.

Sensitive information must never be placed inside HTML comments. Comments included in source code delivered to a browser may still be inspected even though they are not displayed on the webpage.

Use comments for useful developer context, temporary debugging, and source organization. Use version control instead of keeping large amounts of old code permanently commented out.

In the next lesson, you will learn about HTML Links and how to connect pages, websites, document sections, email addresses, and other resources.

Next Lesson →