HTML Comments - Learn It Quicker

Comment Syntax

HTML comments begin with . Everything between these markers is ignored by the browser and not rendered on the page. Comments can span multiple lines and can contain any content except the closing marker.

Comments are visible in the page source code when users view source, so never put sensitive information in comments. Anyone can read your HTML comments by viewing the page source.

Nested comments are not allowed in HTML. You cannot put a comment inside another comment. The first --> will close the comment, regardless of how many <!-- you've opened.

<!-- This is a single-line comment -->

<!-- 
  This is a multi-line comment.
  It can span multiple lines.
  Useful for longer explanations.
-->

<!-- 
  TODO: Add navigation menu
  TODO: Fix responsive layout on mobile
  TODO: Optimize images
-->

<!-- 
  FIXME: This section needs review
  Bug: Form validation not working
-->

Using Comments for Documentation

Use comments to document your code structure, explain complex sections, mark sections of your page, and leave notes for yourself or other developers. Good comments explain why something is done, not just what is done.

Comments can mark the beginning and end of sections, making it easier to navigate large HTML files. This is especially useful when working with templates or large documents.

Document workarounds, browser-specific fixes, and temporary solutions so future developers understand the context and can update the code appropriately.

<!-- ============================================
     HEADER SECTION
     Contains logo, navigation, and search
============================================= -->
<header class="site-header">
  <!-- Logo -->
  <div class="logo">
    <img src="logo.png" alt="Company Logo">
  </div>
  
  <!-- Main Navigation -->
  <nav class="main-nav">
    <ul>
      <li><a href="/">Home</a></li>
      <li><a href="/about">About</a></li>
    </ul>
  </nav>
</header>
<!-- End Header Section -->

<!-- ============================================
     MAIN CONTENT
============================================= -->
<main>
  <!-- Temporary: Using inline styles until CSS is updated -->
  <div style="margin: 20px;">
    Content here
  </div>
</main>

Commenting Out Code

Comments are useful for temporarily disabling code during development and testing. This lets you test changes without deleting code, making it easy to revert if needed.

When commenting out code for testing, add a note explaining why it's commented out and when it can be removed. This prevents commented-out code from lingering in production.

Remove commented-out code before deploying to production. Leaving old, unused code in comments clutters your source and can confuse future developers.

<!-- Testing new layout - can remove old version after approval -->
<!-- <div class="old-layout">
  <h2>Old Header</h2>
  <p>Old content structure</p>
</div> -->

<!-- New layout -->
<div class="new-layout">
  <h2>New Header</h2>
  <p>Improved content structure</p>
</div>

<!-- Temporarily disabled while fixing bug #123 -->
<!-- <script src="analytics.js"></script> -->

<!-- 
  DEPRECATED: Old contact form
  Replace with new form system by 2026-02-01
  Then remove this entirely
-->
<!-- <form action="/old-contact" method="post">
  <!-- form fields -->
</form> -->

Conditional Comments (Legacy IE)

Conditional comments were a Microsoft-specific feature for Internet Explorer. They allowed you to include code that only IE would execute. Modern browsers don't support conditional comments, and they're no longer needed as IE is deprecated.

If you're maintaining legacy code, you might encounter conditional comments. They use special syntax like . These are now obsolete and should be removed in modern web development.

For modern browser compatibility, use feature detection (JavaScript) or CSS feature queries instead of conditional comments.

<!-- 
  LEGACY CODE - Conditional comments (obsolete)
  Only for historical reference - don't use in new projects
-->

<!-- [if IE]>
  <p>You are using Internet Explorer</p>
<![endif] -->

<!-- [if lt IE 9]>
  <script src="html5shiv.js"></script>
<![endif] -->

<!-- 
  MODERN APPROACH - Use feature detection instead
-->
<script>
  // Detect if browser supports a feature
  if ('querySelector' in document) {
    // Use modern features
  } else {
    // Provide fallback
  }
</script>

Comment Best Practices

Write clear, concise comments that add value
Explain why, not just what (the code shows what)
Keep comments up to date when you change code
Remove obsolete comments and commented-out code before production
Don't state the obvious ( is useless)
Use consistent formatting for section markers
Never put passwords, API keys, or sensitive data in comments
Consider that comments are visible in view source
Use TODO, FIXME, HACK, NOTE, etc. as markers for special comments
Document browser-specific workarounds and hacks