HTML comments are special annotations that let you write notes in your code that browsers ignore. They're invisible to visitors but invaluable to developers. Whether you're explaining complex code, leaving reminders, or temporarily disabling sections, comments are an essential tool in your HTML toolkit.
What Are HTML Comments?
Comments are pieces of text in your HTML that browsers completely ignore. They don't display on the page and don't affect how the page works—they exist purely for developers.
MARKUP
<!-- This is a comment. Browsers ignore it completely. -->
<h1>Welcome to My Website</h1>
<!-- The heading above will be visible, but this comment won't be -->
<p>This paragraph is visible to users.</p>💡 Key Point:
While comments don't appear on the visible page, they are visible in the page source. Anyone can view them by right-clicking and selecting "View Page Source." Never put sensitive information in comments!
Comment Syntax
HTML comments use a special syntax that's different from regular HTML tags:
MARKUP
<!-- This is how you write a comment -->The comment starts with <!-- and ends with -->. Everything between these markers is ignored by the browser.
Single-Line Comments
MARKUP
<!-- This is a single-line comment -->
<h1>Title</h1> <!-- You can also add comments after code -->
<!-- Short note about something -->Multi-Line Comments
Comments can span multiple lines, which is useful for longer explanations:
MARKUP
<!--
This is a multi-line comment.
It can span several lines.
Very useful for detailed explanations.
-->
<div class="container">
<!--
The container div holds all the main content.
It's styled with max-width: 1200px in the CSS.
Created: Jan 15, 2024
Last modified: Jan 20, 2024
-->
<h1>Content</h1>
</div>Why Use Comments?
1. Explain Complex Code
Use comments to explain why you did something, not just what you did:
MARKUP
<!-- BAD: Stating the obvious -->
<div class="container">
<!-- This is a div with class container -->
</div>
<!-- GOOD: Explaining the purpose -->
<div class="container">
<!--
Container must stay at 100% width on mobile devices
to prevent horizontal scrolling issues on iPhone 12
-->
</div>2. Organize Sections
Comments help you divide your code into logical sections:
MARKUP
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>My Page</title>
</head>
<body>
<!-- ==================== HEADER ==================== -->
<header>
<h1>Site Title</h1>
<nav>
<!-- Navigation links -->
</nav>
</header>
<!-- ==================== MAIN CONTENT ==================== -->
<main>
<article>
<h2>Article Title</h2>
<p>Content...</p>
</article>
</main>
<!-- ==================== SIDEBAR ==================== -->
<aside>
<h3>Sidebar</h3>
</aside>
<!-- ==================== FOOTER ==================== -->
<footer>
<p>Copyright 2024</p>
</footer>
</body>
</html>3. Temporarily Disable Code
Comments are perfect for testing by temporarily removing code without deleting it:
MARKUP
<div class="hero">
<h1>Welcome</h1>
<!-- Temporarily disabled for testing
<img src="hero-image.jpg" alt="Hero">
<p>Hero description text</p>
-->
<button>Get Started</button>
</div>4. Leave To-Do Notes
MARKUP
<section class="products">
<h2>Our Products</h2>
<!-- TODO: Add product filtering functionality -->
<!-- TODO: Implement pagination when we have more than 20 products -->
<!-- FIXME: Product images not loading on Safari 15 -->
<div class="product-list">
<!-- Products will go here -->
</div>
</section>5. Document Changes and Decisions
MARKUP
<div class="pricing">
<!--
Changed from 3-column to 2-column layout on 2024-01-15
Reason: Better mobile experience and higher conversion rate
Previous layout: pricing-v1.html (archived)
-->
<div class="plan">Basic Plan</div>
<div class="plan">Premium Plan</div>
</div>6. Credit and Attribution
MARKUP
<!--
Lightbox Gallery Component
Created by: John Doe
Date: January 2024
Based on: SimpleLightbox library v2.1
License: MIT
-->
<div class="lightbox-gallery">
<!-- Gallery images -->
</div>Comment Best Practices
1. Write Clear, Concise Comments
MARKUP
<!-- BAD: Vague and unhelpful -->
<!-- stuff -->
<!-- fix this -->
<!-- important! -->
<!-- GOOD: Clear and specific -->
<!-- Product grid uses CSS Grid with 3 columns on desktop -->
<!-- Contact form validation requires email format -->
<!-- Navigation menu collapses into hamburger below 768px -->2. Explain Why, Not What
MARKUP
<!-- BAD: Explaining what the code does (already obvious) -->
<img src="logo.png" alt="Company Logo"> <!-- This is an image -->
<!-- GOOD: Explaining why something is done this way -->
<img src="logo.png" alt="Company Logo" width="200" height="50">
<!-- Width and height prevent layout shift during page load -->3. Keep Comments Up to Date
MARKUP
<!-- BAD: Outdated comment (code changed but comment didn't) -->
<!-- Using jQuery for animations -->
<div class="animate-me"></div>
<script>
// Actually using CSS animations now, not jQuery!
document.querySelector('.animate-me').classList.add('animated');
</script>
<!-- GOOD: Accurate comment -->
<!-- Using CSS animations (transitioned from jQuery Jan 2024) -->
<div class="animate-me"></div>
<script>
document.querySelector('.animate-me').classList.add('animated');
</script>4. Don't Over-Comment
MARKUP
<!-- BAD: Too many obvious comments -->
<!-- Start of header -->
<header>
<!-- Site title -->
<h1>My Site</h1>
<!-- Navigation section -->
<nav>
<!-- Unordered list -->
<ul>
<!-- List item 1 -->
<li><a href="/">Home</a></li>
<!-- List item 2 -->
<li><a href="/about">About</a></li>
</ul>
</nav>
<!-- End of header -->
</header>
<!-- GOOD: Comments only where needed -->
<header>
<h1>My Site</h1>
<nav>
<!-- Main navigation - order matters for accessibility -->
<ul>
<li><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
</nav>
</header>5. Use Consistent Comment Conventions
MARKUP
<!-- Use consistent markers for different types of comments -->
<!-- TODO: Add functionality -->
<!-- FIXME: Bug on mobile devices -->
<!-- NOTE: This section requires JavaScript -->
<!-- HACK: Temporary workaround until API is fixed -->
<!-- DEPRECATED: Will be removed in v2.0 -->
<!-- Or use consistent section dividers -->
<!-- ========================================
SECTION: USER PROFILE
======================================== -->
<!-- ==================== HEADER ==================== -->Where to Use Comments
In the Head Section
MARKUP
<head>
<meta charset="UTF-8">
<title>My Page</title>
<!-- Primary stylesheet -->
<link rel="stylesheet" href="main.css">
<!-- Google Fonts -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<!-- TODO: Add favicon -->
<!-- <link rel="icon" href="favicon.ico"> -->
</head>In the Body Section
MARKUP
<body>
<!-- Skip to main content link for accessibility -->
<a href="#main" class="skip-link">Skip to main content</a>
<header>
<!-- Site branding and navigation -->
</header>
<main id="main">
<!-- Primary page content -->
</main>
<footer>
<!-- Footer information -->
</footer>
</body>Around Complex Structures
MARKUP
<!--
Pricing table uses flexbox for equal-height columns.
Each column has: header, feature list, price, and CTA button.
Minimum of 2 columns, maximum of 4 for optimal display.
-->
<div class="pricing-table">
<div class="pricing-column">
<h3>Basic</h3>
<ul class="features">
<li>Feature 1</li>
<li>Feature 2</li>
</ul>
<p class="price">$9/month</p>
<button>Choose Plan</button>
</div>
<!-- More pricing columns... -->
</div>Commenting Out Code
One of the most common uses of comments is temporarily disabling code:
Commenting Out Single Elements
MARKUP
<div class="content">
<h1>Title</h1>
<p>This paragraph is visible.</p>
<!-- <p>This paragraph is commented out.</p> -->
<p>This paragraph is also visible.</p>
</div>Commenting Out Multiple Elements
MARKUP
<section>
<h2>Active Section</h2>
<p>This is visible.</p>
<!--
<h2>Disabled Section</h2>
<p>This entire section is commented out.</p>
<img src="image.jpg" alt="Image">
<button>Click Me</button>
-->
<p>Back to visible content.</p>
</section>Commenting Out Nested Structures
MARKUP
<!--
<div class="sidebar">
<h3>Sidebar Title</h3>
<ul>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
</ul>
<div class="widget">
<p>Widget content</p>
</div>
</div>
-->Conditional Comments (Legacy IE)
Older versions of Internet Explorer supported conditional comments, which only worked in IE. These are now obsolete but you might see them in legacy code:
MARKUP
<!-- LEGACY: Internet Explorer conditional comments (don't use in new code) -->
<!--[if IE]>
<p>You are using Internet Explorer.</p>
<![endif]-->
<!--[if IE 9]>
<link rel="stylesheet" href="ie9.css">
<![endif]-->
<!--[if lt IE 9]>
<script src="html5shiv.js"></script>
<![endif]-->
<!--[if !IE]><!-->
<p>You are NOT using Internet Explorer.</p>
<!--<![endif]-->📝 Note:
Conditional comments are obsolete since Internet Explorer is discontinued. Modern code should not use them. Use feature detection with JavaScript instead.
Security Considerations
Comments Are Visible in Page Source
Remember: Anyone can view your HTML comments by viewing the page source!
MARKUP
<!-- NEVER put sensitive information in comments! -->
<!-- BAD: Exposing sensitive info -->
<!-- Database password: admin123 -->
<!-- API key: sk_live_51Hx... -->
<!-- Admin panel: /secret-admin-page -->
<!-- TODO: Remove test credit card 4111-1111-1111-1111 -->
<!-- GOOD: Safe, non-sensitive comments -->
<!-- Contact form uses Formspree for submission -->
<!-- Navigation uses Bootstrap 5 classes -->
<!-- TODO: Optimize hero image for mobile devices -->Don't Expose Internal Structure
MARKUP
<!-- BAD: Revealing too much about internal systems -->
<!--
Server: Ubuntu 20.04 on AWS EC2 t2.micro
Database: MySQL 8.0 on RDS instance db-prod-01
Redis cache on port 6379
Internal API endpoint: https://internal-api.company.local/v1
-->
<!-- GOOD: Generic, safe information -->
<!--
Contact form validation
Requires: Name, Email, Message
Max message length: 1000 characters
-->Common Comment Mistakes
Mistake 1: Nested Comments (Don't Work!)
MARKUP
<!-- WRONG: You can't nest comments -->
<!-- Outer comment
<div>Some content</div>
<!-- Inner comment (this breaks everything!) -->
<div>More content</div>
-->
<!-- CORRECT: Use one comment block -->
<!--
All content commented out together
<div>Some content</div>
Note about something
<div>More content</div>
-->Mistake 2: Double Dashes Inside Comments
MARKUP
<!-- PROBLEMATIC: Double dashes inside can cause issues -->
<!-- This is a comment -- with double dashes -- inside -->
<!-- BETTER: Avoid double dashes inside comments -->
<!-- This is a comment - with single dashes - inside -->
<!-- Or use different punctuation like === or *** -->Mistake 3: Forgetting to Close Comments
MARKUP
<!-- WRONG: Comment never closes
<div>
<h1>This won't appear!</h1>
<p>Everything after the comment opening disappears</p>
</div>
<!-- CORRECT: Always close comments -->
<!-- This is a proper comment -->
<div>
<h1>This appears correctly</h1>
<p>Everything works as expected</p>
</div>Mistake 4: Wrong Comment Syntax
MARKUP
<!-- WRONG: Using wrong syntax (these don't work in HTML) -->
// This is not an HTML comment (this is JavaScript/CSS comment syntax)
/* This is also not an HTML comment */
# This is not an HTML comment either
<!-- CORRECT: HTML comment syntax -->
<!-- This is the proper HTML comment syntax -->Removing Comments in Production
While comments are helpful during development, you might want to remove them from production code to reduce file size:
- Build tools: Use tools like Webpack, Gulp, or Grunt to automatically strip comments
- Minifiers: HTML minifiers typically remove comments automatically
- Server-side: Configure your server to remove comments before sending HTML
However, some comments might be intentionally kept:
- Copyright notices
- License information
- Important legal disclaimers
- Tool-specific comments (like for analytics or debugging)
Complete Example with Comments
index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- Page title and SEO -->
<title>My Portfolio - Web Developer</title>
<meta name="description" content="Portfolio of John Doe, web developer">
<!-- Stylesheets -->
<link rel="stylesheet" href="main.css">
<!-- TODO: Add dark mode stylesheet -->
<!-- Favicon -->
<link rel="icon" href="favicon.ico">
</head>
<body>
<!-- ==================== HEADER ==================== -->
<header>
<!-- Site branding -->
<div class="logo">
<img src="logo.png" alt="John Doe">
</div>
<!-- Main navigation -->
<nav>
<ul>
<li><a href="#home">Home</a></li>
<li><a href="#about">About</a></li>
<li><a href="#portfolio">Portfolio</a></li>
<li><a href="#contact">Contact</a></li>
</ul>
</nav>
</header>
<!-- ==================== HERO SECTION ==================== -->
<section id="home" class="hero">
<h1>Welcome to My Portfolio</h1>
<p>I create beautiful, functional websites</p>
<!-- CTA button -->
<a href="#contact" class="btn">Get In Touch</a>
</section>
<!-- ==================== ABOUT SECTION ==================== -->
<section id="about" class="about">
<h2>About Me</h2>
<!--
About section uses two-column layout on desktop:
- Left: Profile image
- Right: Bio text
Stacks vertically on mobile
-->
<div class="about-content">
<div class="profile-image">
<img src="profile.jpg" alt="John Doe">
</div>
<div class="bio">
<p>I'm a web developer with 5 years of experience...</p>
<!-- Skills list -->
<h3>Skills</h3>
<ul>
<li>HTML & CSS</li>
<li>JavaScript</li>
<li>React</li>
<!-- TODO: Add more skills as learned -->
</ul>
</div>
</div>
</section>
<!-- ==================== PORTFOLIO SECTION ==================== -->
<section id="portfolio" class="portfolio">
<h2>My Work</h2>
<!--
Portfolio grid:
- 3 columns on desktop
- 2 columns on tablet
- 1 column on mobile
-->
<div class="portfolio-grid">
<div class="project">
<img src="project1.jpg" alt="E-commerce Website">
<h3>E-commerce Website</h3>
<p>A fully functional online store...</p>
</div>
<!-- More projects... -->
<!-- Temporarily hidden project
<div class="project">
<img src="project-old.jpg" alt="Old Project">
<h3>Old Project</h3>
<p>This project is being updated...</p>
</div>
-->
</div>
</section>
<!-- ==================== CONTACT SECTION ==================== -->
<section id="contact" class="contact">
<h2>Get In Touch</h2>
<!--
Contact form validation handled by contact.js
Requires: name, email, message
NOTE: Form submits to Formspree.io
-->
<form action="https://formspree.io/f/xyz" method="POST">
<label for="name">Name:</label>
<input type="text" id="name" name="name" required>
<label for="email">Email:</label>
<input type="email" id="email" name="email" required>
<label for="message">Message:</label>
<textarea id="message" name="message" rows="5" required></textarea>
<button type="submit">Send Message</button>
</form>
</section>
<!-- ==================== FOOTER ==================== -->
<footer>
<p>© 2024 John Doe. All rights reserved.</p>
<!-- Social media links -->
<div class="social">
<a href="https://github.com/johndoe">GitHub</a>
<a href="https://linkedin.com/in/johndoe">LinkedIn</a>
<a href="https://twitter.com/johndoe">Twitter</a>
</div>
</footer>
<!-- JavaScript -->
<script src="main.js"></script>
<!-- Google Analytics -->
<!-- <script src="analytics.js"></script> -->
</body>
</html>Key Takeaways
- Comments use the syntax
<!-- comment text --> - Browsers completely ignore commented content
- Comments are visible in page source - never include sensitive info
- Use comments to explain why, not what
- Comments can span multiple lines
- You cannot nest comments inside other comments
- Use comments to organize code sections
- Temporarily disable code by wrapping it in comments
- Keep comments up-to-date when code changes
- Don't over-comment obvious code
- Consider removing comments in production for performance
- Use consistent comment conventions (TODO, FIXME, NOTE, etc.)
What's Next?
Congratulations! You've completed the "HTML Document Structure" category. You now understand the foundation of every HTML document—from DOCTYPE declarations to the html, head, and body elements, meta tags, and comments.
Next, we'll dive into "Text and Formatting". You'll learn how to create headings, paragraphs, format text, add line breaks, create quotes, and much more. This is where you'll start making your content look exactly how you want it!
Get ready to explore Topic 12: Headings (h1-h6) and discover how to structure your content with proper heading hierarchy!