HTML Comments Guide
Writing Notes for Your Future Self
There's a specific experience every developer has at least once: opening a file you wrote three months ago, staring at a section of HTML, and having no memory of why you did it that way or what half the classes are for. Sometimes you wrote it yourself and it's still opaque. Comments are the fix for that. They're notes written directly in the source code, completely invisible to the browser and to anyone viewing the page - they exist only for the people reading the HTML. A well-commented file reads like annotated code: you can follow not just what's there but why.
Key Concepts
Documentation- Comments explain the purpose and logic behind code - the why, not just the what.Invisibility- HTML comments are completely ignored by browsers and never displayed to visitors. They exist only in the source code.Maintenance- Good comments make a codebase navigable for anyone who works on it later, including yourself.
What is an HTML Comment?
An HTML comment is text inside your HTML file that the browser skips entirely. It never renders, never affects layout, and never shows up in the page as visible content. The only way to see it is to look at the HTML source directly. Comments serve a few distinct purposes: documenting what a section does, explaining why you made a specific choice, leaving reminders or TODO notes for yourself or teammates, and temporarily disabling code during testing without deleting it.
Comment Properties
Annotation- Comments add context to code that isn't visible to end users or expressed by the HTML itself.Documentation- They record the purpose of sections, non-obvious decisions, and anything future readers would need to understand.Debugging- Comments let you temporarily disable sections of HTML without deleting them, which is useful when isolating problems.
Comments in Context
Here's what comments look like inside a real HTML document - single-line, inline, and multi-line all in one place.
1<!DOCTYPE html>
2<html>
3<head>
4 <title>My Document</title>
5</head>
6<body>
7 <!-- This is the main header for the page -->
8 <h1>Welcome to My Website</h1>
9
10 <p>This paragraph is visible to users.</p> <!-- Brief inline note -->
11
12 <!--
13 Multi-line comment for longer explanations.
14 Useful when you need to describe something complex
15 or leave context that won't fit on one line.
16 -->
17</body>
18</html>Comment Styles
Single-line- A comment on its own line before the element it describes. The most common placement.Inline- A comment on the same line as code - good for very brief notes, though it can clutter the line.Multi-line- A comment spanning several lines, used when the explanation needs more space.
Why Use Comments: The Power of Invisible Notes
The most valuable comments explain things that aren't obvious from reading the code itself. Why is this navigation marked as generated by the CMS? Why does this link open in a new tab? Why does this section use a specific workaround? The code shows what's there; comments explain the decisions behind it.
1<!-- Main navigation - generated dynamically by the CMS, do not edit directly -->
2<nav id="main-nav">...</nav>
3
4<!-- Product listing section: items are pulled from the database via PHP include -->
5<section class="product-list">
6 ...
7</section>
8
9<!-- Using target="_blank" here intentionally to keep users on the site during external visits -->
10<a href="https://external-site.com" target="_blank" rel="noopener">Visit our Partner</a>Debugging and Testing: Commenting Out Code
When you're testing a page and want to temporarily hide a section without deleting it, you wrap it in a comment. This is called commenting out code. It's faster than cutting and pasting somewhere else, and when you're done testing you just remove the comment markers to restore the HTML. The code stays exactly where it was.
1<h1>This heading is active and visible</h1>
2
3<!-- Temporarily disabled for testing: -->
4<!--
5<p>This paragraph is hidden during testing.</p>
6<img src="test-banner.jpg" alt="Old banner">
7-->
8
9<p>This paragraph is still active and visible.</p>Organization and Readability
In long HTML files - and some files get very long - comments serve as section markers that let you navigate the structure without reading every line. The start and end pattern for major sections is a common convention: you can scan comments quickly to find where the footer starts, where the product section ends, or where the hero image block lives.
1<body>
2 <!-- START HEADER -->
3 <header>...</header>
4 <!-- END HEADER -->
5
6 <!-- START MAIN CONTENT -->
7 <main>
8 <!-- HERO SECTION -->
9 <section>...</section>
10
11 <!-- FEATURED PRODUCTS -->
12 <section>...</section>
13
14 <!-- TESTIMONIALS -->
15 <section>...</section>
16 </main>
17 <!-- END MAIN CONTENT -->
18
19 <!-- START FOOTER -->
20 <footer>...</footer>
21 <!-- END FOOTER -->
22</body>Communication with Other Developers
On a team, comments become a lightweight communication channel - leaving notes about what's pending, what's fragile, and what's about to change. TODO and FYI conventions are common enough that most editors will highlight them specially. They're not a substitute for a proper task tracker but for things that live right next to the code they refer to, an inline comment is often more useful than a ticket.
1<!-- TODO: Replace placeholder with final product shot from the design team -->
2<img src="placeholder.jpg" alt="Product image placeholder">
3
4<!-- FYI: This form action URL is changing after the API update scheduled for next week -->
5<form action="/old-submit-url">...</form>Best Practices for Writing Effective Comments
The useful comment explains why, not what. The code already shows what's there - a comment that says 'submit button' next to a submit button adds nothing. A comment that says 'uses native HTML5 validation before the POST fires' adds something you can't see from the element itself. The second habit worth building is keeping comments updated when code changes. A comment that describes the old behavior after a refactor is actively misleading, which is worse than no comment at all.
1<!-- Less useful - describes what you can already see -->
2<button>Submit</button> <!-- This is a submit button -->
3
4<!-- More useful - explains a decision that isn't visible in the code -->
5<button>Submit</button> <!-- Uses native HTML5 validation; JS handler fires only if validation passes -->
6
7<!-- Useful - explains why a workaround exists -->
8<div class="clearfix"><!-- Clearfix needed here because the floated sidebar breaks the parent height in IE11 --></div>What Not to Do with Comments
Comments are visible in source code. Anyone who right-clicks a page and selects View Page Source sees all your comments. This means comments are not a safe place for passwords, API keys, private credentials, or anything you wouldn't want publicly readable - and these things end up in comments more often than you'd expect. The other common mistake is leaving large blocks of commented-out code sitting in a file indefinitely. If the code isn't needed, delete it. Version control keeps the history and you can always recover it if needed. Abandoned commented-out blocks create confusion about whether the code is actually disabled or just forgotten.
1<!-- WRONG - comments are visible to anyone viewing source -->
2<!-- Database password: mySecretPassword123 -->
3<!-- API key: sk-abc123xyz -->
4
5<!-- WRONG - delete unused code instead of leaving it commented out indefinitely -->
6<!--
7<div class="old-feature">
8 ...
9</div>
10-->Your Code's Personal Diary
Comments are one of the smaller technical things with an outsized effect on how a codebase feels to work in. A file with good comments is a file you can come back to after three months away and still understand quickly. A file without them requires reverse engineering. Neither takes much time to write when you're already writing the HTML - the habit just needs to be there. The short version: explain why, keep them updated, never put credentials in them, and delete code rather than leaving it commented out forever
The Syntax of a Comment
HTML comments start with left-angle-bracket exclamation-mark double-dash and end with double-dash right-angle-bracket. Everything between those markers is treated as a comment and ignored by the browser. The syntax is the same whether the comment is one word or twenty lines.
Syntax Elements
Opening marker- The comment begins with the less-than sign, exclamation mark, and two hyphens.Closing marker- The comment ends with two hyphens and the greater-than sign. Everything between is the comment.No nesting- You cannot put a comment inside another comment. The first closing marker ends the comment, which can cause unexpected behavior.