HTML Comments: Notes Only Developers Can See

Notes in the Margin of the Register

Visit a busy kirana store in the evening and look at the big register on the counter. Next to the day’s sales, you will often see small notes in the margin: “Sharma ji will pay on Friday”, “Oil stock low, call the supplier”, “Do not sell the old batch of biscuits”. The morning worker writes them for the evening worker. Customers never read them, but they keep the shop running smoothly.

Web pages have the same thing. An HTML comment is a note inside your code that the browser does not show on the page. Developers use comments to explain their code, to leave messages for teammates, and to switch parts of a page off for a while without deleting them.

In this lesson you will write comments for the website of Gupta Kirana Store, so that the next person who edits the page knows exactly what to do.

How to Write a Comment

A comment starts with <!-- and ends with -->. Everything in between is ignored by the browser.

Run this example. The comment line is in the code, but it does not appear on the page:

<!-- This is a comment. The browser does not show it. -->
<h1>Gupta Kirana Store</h1>
<p>Fresh vegetables arrive every morning at 7:00 AM.</p>

You have already seen comments in the practice tasks of earlier lessons: the TODO lines in the starter code were comments.

Comments over many lines

A comment does not have to fit on one line. It continues until the browser finds -->. This is useful for a short note at the top of a file:

<!--
  Shop page for Gupta Kirana Store.
  Written by Ravi, 10 June.
  Prices are updated every Monday.
-->
<h1>Gupta Kirana Store</h1>
<p>Rice, dal, atta, oil and spices at fair prices.</p>

Use 1: Notes for Your Teammates (and Your Future Self)

Real websites are big. A shop page might have hundreds of lines. Comments work like signboards inside the code: they mark where each part starts and give instructions to whoever edits it next.

<!-- ===== TOP: shop name and timings ===== -->
<h1>Gupta Kirana Store</h1>
<p>Open 7:00 AM to 10:00 PM</p>

<!-- ===== OFFERS: change every Monday ===== -->
<h2>This Week's Offers</h2>
<ul>
  <li>Toor dal, 1 kg: ₹140</li>
  <!-- Ask Mr. Gupta before adding more offers -->
  <li>Sunflower oil, 1 litre: ₹155</li>
</ul>

<!-- ===== BOTTOM: address ===== -->
<p>Shop No. 4, Station Road</p>

This also helps you. When you open your own code after three months, you will be glad you left notes. Good comments explain why something is there, or what someone should be careful about. You do not need a comment for things the code already says clearly. <!-- This is a heading --> above an <h2> adds nothing.

Use 2: Turning Code Off for a While

Suppose mango pickle is out of stock. You could delete that line, but then you would have to type it again next week. Instead, put it inside a comment. The browser skips it, and you can bring it back by removing the comment marks. Developers call this commenting out code.

<h2>Today's Offers</h2>
<ul>
  <li>Sugar, 1 kg: ₹44</li>
  <!-- <li>Mango pickle, 500 g: ₹90</li> -->
  <li>Tea powder, 250 g: ₹120</li>
</ul>

<!--
<h2>Diwali Gift Hampers</h2>
<p>Coming soon. Book your hamper at the counter.</p>
-->

Run it and notice that the mango pickle and the whole Diwali section have disappeared from the page. Remove the <!-- and --> around one of them and run it again: it comes back.

Commenting out is also a great way to find a bug. If part of your page looks wrong, comment out one section at a time. When the problem disappears, you have found the section that causes it.

The Keyboard Shortcut in VS Code

Typing <!-- and --> again and again is slow. In VS Code:

1. Put your cursor on a line, or select several lines.
2. Press Ctrl + / (on a Mac, Cmd + /).
3. VS Code wraps the line in comment marks. Press the same keys again to remove them.

The shortcut is smart: inside a <style> block it writes a CSS comment, and inside a <script> block it writes a JavaScript comment, because those languages use different comment marks. You will meet them in the CSS and JavaScript lessons.

Comments Are Hidden, Not Secret

This is the most important rule in this lesson. A comment is hidden from the page, but it is not hidden from people. Anyone can see your full HTML code, comments included:

• Right-click the page and choose View page source, or press Ctrl + U (on a Mac, Cmd + Option + U).
• Or open the browser’s developer tools with F12.

So a comment like the one below is a serious mistake. The page looks normal, but the login details are visible to every visitor who opens the source:

<h1>Gupta Kirana Store</h1>
<!-- Admin login: ravi / gupta1234 -->
<p>Welcome! Order your monthly groceries online.</p>

The register margin is safe because only shop staff can read it. A web page is like a register left open on the footpath: anyone walking past can read every note. Never put passwords, PIN numbers, private keys or customer details in a comment. Also avoid rude remarks about customers or colleagues. Someone will read them one day.

Real-Life Example: The Gupta Kirana Store Page

Ravi works the morning shift and updates the shop’s web page. Anjali works the evening shift and edits it too. Ravi uses comments to label each section, leave a warning about the Sunday timings, and switch off an item that is out of stock:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Gupta Kirana Store</title>
</head>
<body>
  <!-- ===== HEADER ===== -->
  <h1>Gupta Kirana Store</h1>
  <p>Your daily needs, one minute from Station Road.</p>

  <!-- ===== TIMINGS =====
       Note for evening shift: Sunday timing changes in winter.
       Check the notice board before changing it here. -->
  <h2>Timings</h2>
  <p>Monday to Saturday: 7:00 AM to 10:00 PM</p>
  <p>Sunday: 8:00 AM to 1:00 PM</p>

  <!-- ===== OFFERS (update every Monday) ===== -->
  <h2>This Week's Offers</h2>
  <ul>
    <li>Toor dal, 1 kg: ₹140</li>
    <li>Basmati rice, 5 kg: ₹520</li>
    <!-- Out of stock. Turn this back on when the new stock arrives.
    <li>Groundnut oil, 1 litre: ₹190</li>
    -->
    <li>Washing powder, 1 kg: ₹95</li>
  </ul>

  <!-- ===== PAYMENT ===== -->
  <h2>Payment</h2>
  <p>We accept cash and UPI.</p>
</body>
</html>

Try these changes, one at a time, and press Run after each:

1. The groundnut oil is back in stock. Remove the comment around it so it appears on the page.
2. Comment out the whole Payment section.
3. Add your own note at the top of the body: who you are and today’s date.

Common Mistakes (and How to Fix Them)

• Forgetting to close a comment. If you write <!-- and forget -->, everything after it disappears from the page. If half your page vanishes after an edit, look for an unclosed comment first.
• Putting secrets in comments. As you saw above, comments are visible in View Source. Keep passwords and private data out of HTML completely.
• Leaving old code commented out forever. A few lines are fine for a week. Hundreds of lines of dead code make the file hard to read. Delete what you will never need again.
• Putting a comment inside a comment. Comments cannot be nested. The first --> ends the comment, and whatever follows shows up on the page. Run this broken example and look at the stray text:

<!-- Old offers
  <!-- Sugar offer ended -->
  <p>Sugar, 1 kg: ₹40</p>
-->
<p>Welcome to Gupta Kirana Store.</p>

The fix: use one comment only, and write the inner note as plain text inside it:

<!-- Old offers. Sugar offer ended.
  <p>Sugar, 1 kg: ₹40</p>
-->
<p>Welcome to Gupta Kirana Store.</p>

Practice Task: Leave Notes for the Next Shift

Anjali runs Chai Corner near the college gate and has asked you to tidy up the menu page. Use comments to:

• Add a note at the top of the body saying who checked the prices and when
• Label each section (header, menu, monsoon special) with a comment
• Turn off the cold coffee line, because it is not sold in the rainy season, without deleting it
• Leave a note above the Monsoon Special saying it should be removed in October

Try the Ctrl + / shortcut if you are working in VS Code.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Chai Corner Menu</title>
</head>
<body>
  <h1>Chai Corner</h1>
  <p>Hot tea and snacks near the college gate.</p>

  <h2>Menu</h2>
  <ul>
    <li>Cutting chai: ₹15</li>
    <li>Masala chai: ₹20</li>
    <li>Cold coffee: ₹40</li>
    <li>Samosa: ₹15</li>
  </ul>

  <h2>Monsoon Special</h2>
  <p>Hot pakoras with every masala chai.</p>
</body>
</html>

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Chai Corner Menu</title>
</head>
<body>
  <!-- Menu page for Chai Corner. Prices checked by Anjali, 2 July. -->

  <!-- ===== HEADER ===== -->
  <h1>Chai Corner</h1>
  <p>Hot tea and snacks near the college gate.</p>

  <!-- ===== MENU ===== -->
  <h2>Menu</h2>
  <ul>
    <li>Cutting chai: ₹15</li>
    <li>Masala chai: ₹20</li>
    <!-- Cold coffee is off until summer.
    <li>Cold coffee: ₹40</li>
    -->
    <li>Samosa: ₹15</li>
  </ul>

  <!-- ===== MONSOON SPECIAL =====
       Remove this section in October. -->
  <h2>Monsoon Special</h2>
  <p>Hot pakoras with every masala chai.</p>
</body>
</html>

Key Takeaways

• A comment starts with <!-- and ends with -->. The browser does not show it.
• Use comments to label sections and explain why, for teammates and for your future self.
• “Commenting out” code switches it off without deleting it, which also helps you find bugs.
• Press Ctrl + / (Cmd + / on a Mac) in VS Code to add or remove a comment.
• Comments are visible in View Source. Never put passwords or private information in them.
• Comments cannot be nested: the first --> ends the comment.