HTML Comments Explained - Writing Code Notes

Previous Next

The larger your project and the longer your code, the more you need a tool that helps you understand what you wrote. This tool is called a comment. A comment is text you write inside the code - the browser ignores it completely and does not show it to visitors - but it remains visible to you and your teammates in the code.

What Is a Comment in HTML?

Imagine you are reading a book and you want to write a pencil note in the margin. The note is just for you and isn't printed in the official book. That's exactly what a comment does in HTML.

Simple definition: A comment is text you write between two special HTML markers - it appears in the code but never appears on the browser page.

Comment Syntax - How Is It Written?

In HTML, a comment starts with :

<!-- This is a comment - it will never appear in the browser -->

<p>This paragraph will appear to the visitor.</p>

<!-- You can place a comment anywhere in the code -->

If you open this code in the browser, you will see that the page shows only:

This paragraph will appear to the visitor.

Remember: A comment doesn't appear on the page, but it does appear in the page source (View Page Source). So never put any secret information in it, such as usernames or passwords.

Multi-Line Comment

A comment can span multiple lines:

<!--
    This is a long comment
    that spans multiple lines
    useful for explaining large parts of the code
-->

<h1>Page Title</h1>

Why Do We Use Comments?

Comments have three main uses:

1. Explain the code to yourself or your teammates

<!-- Main header section -->
<header>
    <h1>DevArabi Website</h1>
</header>

<!-- Main content section -->
<main>
    <p>Welcome to our website.</p>
</main>

<!-- Footer section -->
<footer>
    <p>All rights reserved 2025</p>
</footer>

2. Temporarily disable a piece of code

Instead of deleting code you may need later, put it inside a comment to disable it temporarily:

<!-- Old image - temporarily disabled -->
<!-- <img src="/images/old-logo.png" alt="Old logo"> -->

<!-- New image -->
<img src="/images/new-logo.png" alt="New logo">

3. Organize the page and split it into sections

<!-- ============================
     Section: Home Page
     Created: 2025
     ========================== -->

<section>
    <h2>Welcome!</h2>
</section>

<!-- ============================
     End of Home Page Section
     ========================== -->

Pro tip: Professional developers write clear comments that explain why the code was written - not just what it does. Code with good comments saves hours of searching when you return to it later.

Comment vs. Normal Content - Comparison

Code	Shown in Browser?	Shown in View Page Source?
`<p>Hello</p>`	Yes Yes	Yes Yes
`<!-- Note -->`	No No	Yes Yes
`<!-- <p>Disabled</p> -->`	No No	Yes Yes

Important Things to Know About Comments

You cannot write a comment inside another tag: <p > does not work.
Comments do not nest - if you open a first  you encounter closes the comment.
You can comment out anything: full HTML tags, text, even inline CSS.
File size increases slightly with comments, but it doesn't noticeably affect performance.

Important security warning: Never put in comments: passwords, API keys, database information, or any sensitive data. Anyone can view the full page source with one click (Ctrl + U in most browsers).

Practical Example - A Page Organized with Comments

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>My Organized Page</title>
    <!-- Main CSS file -->
    <link rel="stylesheet" href="style.css">
</head>
<body>

    <!-- === Header === -->
    <h1>Welcome to My Page</h1>

    <!-- === Main Content === -->
    <p>This is the main content of the page.</p>

    <!-- TODO: Add an image here later -->

    <!-- === Footer === -->
    <p>Copyright (c) 2025</p>

</body>
</html>

Notice the use of TODO: inside the comment - this is a very common habit among developers to remind themselves of tasks that are not finished yet.

Frequently Asked Questions - FAQ

Do comments affect page speed?

Their impact is very small - they add a few bytes to the file size. In production projects, comments are sometimes removed automatically by minification tools. For learning, don't worry about this at all.

Do comments affect SEO and Google ranking?

They do not affect your Google ranking in any way. Google completely ignores comments when indexing a page.

Can I comment out full HTML tags with their attributes?

Yes, you can put any HTML code inside a comment no matter how long or complex it is, and it will stop working completely.

When should I write a comment?

Write a comment at: the start of each main section of the page, when there is complex code that others won't understand quickly, when temporarily disabling code, and when leaving reminders (TODO) for future tasks.

Great! Comments are now part of your programming tools. In the next lesson we will learn HTML headings - from <h1> to <h6> and how to choose the correct level for each heading.