HTML Comments Guide

Learn how to effectively use comments in your HTML documents

Why Use HTML Comments?

HTML comments are an essential tool for developers to document code, leave notes, and temporarily disable sections without deletion. While invisible to end users viewing the rendered page, comments remain in the source code where they serve several important purposes:

Code Documentation: Explain complex sections or document the purpose of elements
Team Communication: Leave notes for other developers working on the same codebase
Development Markers: Use TODO, FIXME, or other tags to track work items
Debugging: Temporarily disable code blocks to isolate issues
Build Directives: Some tools process special comment formats during builds

Note: While comments are extremely useful during development, excessive or outdated comments can clutter your code. Aim for a balance between helpful documentation and clean, maintainable markup.

Single-line Comments

Comments that occupy a single line in your code

Usage: For brief notes or to temporarily disable a single line

Multi-line Comments

Comments that span multiple lines

<!-- 
  This is a multi-line comment
  that can span as many lines
  as you need
-->

Usage: For longer explanations or to disable blocks of code

Inline Comments

Comments placed within a line of code

<p>This is text  with an inline comment</p>

Usage: To annotate specific parts of a line (use sparingly)

Commenting Out Code

Disabling HTML without deleting it

<!-- 
<div>
  <p>Temporarily disabled content</p>
</div>
-->

Usage: For debugging or temporarily removing elements

Development Notes

Leave notes for yourself or other developers

<!-- TODO: Update this section with new images -->
<!-- FIXME: Check mobile responsiveness -->
<!-- OPTIMIZE: Reduce image sizes --><!-- TODO: Update this section with new images -->
<!-- FIXME: Check mobile responsiveness -->
<!-- OPTIMIZE: Reduce image sizes -->

Benefits: Helps track work items and issues directly in code

Section Headers

Documenting major sections of your HTML

<!-- 
  ======================
  HEADER SECTION
  Includes: Logo, navigation, search
  Last updated: 2023-06-15
====================== 
-->
<header>...</header><!-- 
  ======================
  HEADER SECTION
  Includes: Logo, navigation, search
  Last updated: 2023-06-15
====================== 
-->
<header>...</header>

Benefits: Makes large files more navigable and maintainable

Templating Notes

Notes for template systems or CMS

<!-- 
  TEMPLATE VARIABLES:
  {user_name} - Displays the current user's name
  {user_avatar} - Displays the user's profile image
--><!-- 
  TEMPLATE VARIABLES:
  {user_name} - Displays the current user's name
  {user_avatar} - Displays the user's profile image
-->

Benefits: Documents dynamic content placeholders

Browser-Specific Workarounds

Documenting special cases

<!-- 
  IE11 FIX: 
  The following div needs position:relative
  to prevent rendering issues in IE11
--><!-- 
  IE11 FIX: 
  The following div needs position:relative
  to prevent rendering issues in IE11
-->

Benefits: Explains why non-standard code exists

Comment-Based Documentation

Generate documentation from comments

<!-- 
  @component: user-profile-card
  @description: Displays user profile information
  @props:
    - name: string (required)
    - avatar: url
    - role: string
  @example:
    <user-profile-card 
      name="John Doe"
      avatar="/images/john.jpg"
      role="Developer"
    />
--><!-- 
  @component: user-profile-card
  @description: Displays user profile information
  @props:
    - name: string (required)
    - avatar: url
    - role: string
  @example:
    <user-profile-card 
      name="John Doe"
      avatar="/images/john.jpg"
      role="Developer"
    />
-->

Use Case: For documentation generators or design systems

Build Process Directives

Comments processed by build tools

<!-- build:include header.html -->
<!-- /build -->

<!-- build:js bundle.min.js -->
<script src="jquery.js"></script>
<script src="app.js"></script>
<!-- /build --><!-- build:include header.html -->
<!-- /build -->

<!-- build:js bundle.min.js -->
<script src="jquery.js"></script>
<script src="app.js"></script>
<!-- /build -->

Use Case: Used by tools like HTML processors or module bundlers

Conditional Comments (Deprecated)

Internet Explorer-specific comments

<!--[if IE 8]>
  <p>You're using IE8 - consider upgrading</p>
<![endif]--><!--[if IE 8]>
  <p>You're using IE8 - consider upgrading</p>
<![endif]-->

Use Case:

Note: Deprecated feature - included for historical context

Clarity Over Quantity

Make comments meaningful and concise

Not Recommended

<!-- Navigation --><!-- Navigation -->

Explanation: Good comments explain purpose, not just label

Avoid Redundant Comments

Don't state the obvious

Not Recommended

<!-- This is a div --><div></div><!-- This is a div --><div></div>

Explanation: Comments should add value beyond what's visible

Keep Comments Updated

Outdated comments can mislead

Not Recommended

<!-- TODO: Update this (from 2019) --><!-- TODO: Update this (from 2019) -->

Explanation: Regularly review and update or remove stale comments

Security Considerations

Avoid sensitive information in comments

Not Recommended

<!-- API key: 12345-abcde (will expire 2024) --><!-- API key: 12345-abcde (will expire 2024) -->

Explanation: Comments are visible in page source to anyone

Documenting a Component

<!-- 
  COMPONENT: product-card
  DESCRIPTION: Displays a product with image, title, price
  PROPS:
    - id: number (required)
    - title: string (required)
    - price: number (required)
    - image: string (optional)
    - onSale: boolean (default: false)
  EXAMPLE:
    <product-card 
      id="123" 
      title="Wireless Headphones" 
      price="99.99"
      image="/products/headphones.jpg"
      onSale="true"
    />
-->
<div class="product-card" data-id="123">
  <img src="/products/headphones.jpg" alt="Wireless Headphones">
  <h3>Wireless Headphones</h3>
  <p class="price">$99.99</p>
  <span class="sale-badge">Sale</span>
</div><!-- 
  COMPONENT: product-card
  DESCRIPTION: Displays a product with image, title, price
  PROPS:
    - id: number (required)
    - title: string (required)
    - price: number (required)
    - image: string (optional)
    - onSale: boolean (default: false)
  EXAMPLE:
    <product-card 
      id="123" 
      title="Wireless Headphones" 
      price="99.99"
      image="/products/headphones.jpg"
      onSale="true"
    />
-->
<div class="product-card" data-id="123">
  <img src="/products/headphones.jpg" alt="Wireless Headphones">
  <h3>Wireless Headphones</h3>
  <p class="price">$99.99</p>
  <span class="sale-badge">Sale</span>
</div>

Development Workflow

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- TODO: Update meta description -->
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website</title>
  
  <!-- FIXME: Replace with CDN link in production -->
  <link rel="stylesheet" href="styles/local.css">
</head>
<body>
  <!-- 
    SECTION: Main navigation
    Last updated: 2023-06-10 by Developer Name
    Notes: Mobile menu needs accessibility review
  -->
  <nav class="main-nav">...</nav>
  
  <!-- TEMPORARY: Disabling hero section for A/B test -->
  <!--
  <section class="hero">...</section>
  -->
  
  <!-- 
    SECTION: Product grid
    TODO: Implement lazy loading
    FIXME: Images not optimized for mobile
  -->
  <section class="products">...</section>
</body>
</html><!DOCTYPE html>
<html lang="en">
<head>
  <!-- TODO: Update meta description -->
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website</title>
  
  <!-- FIXME: Replace with CDN link in production -->
  <link rel="stylesheet" href="styles/local.css">
</head>
<body>
  <!-- 
    SECTION: Main navigation
    Last updated: 2023-06-10 by Developer Name
    Notes: Mobile menu needs accessibility review
  -->
  <nav class="main-nav">...</nav>
  
  <!-- TEMPORARY: Disabling hero section for A/B test -->
  <!--
  <section class="hero">...</section>
  -->
  
  <!-- 
    SECTION: Product grid
    TODO: Implement lazy loading
    FIXME: Images not optimized for mobile
  -->
  <section class="products">...</section>
</body>
</html>

Build Process Integration

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- build:css css/styles.min.css -->
  <link rel="stylesheet" href="css/normalize.css">
  <link rel="stylesheet" href="css/base.css">
  <link rel="stylesheet" href="css/components.css">
  <!-- /build -->
  
  <!-- build:js js/app.min.js -->
  <script src="js/jquery.js"></script>
  <script src="js/app.js"></script>
  <!-- /build -->
</head>
<body>
  <!-- build:include header.html -->
  <!-- /build -->
  
  <main>
    <!-- build:process echo "Hello, <%= name %>" -->
    <p>Dynamic content will appear here</p>
    <!-- /build -->
  </main>
  
  <!-- build:include footer.html -->
  <!-- /build -->
</body>
</html><!DOCTYPE html>
<html lang="en">
<head>
  <!-- build:css css/styles.min.css -->
  <link rel="stylesheet" href="css/normalize.css">
  <link rel="stylesheet" href="css/base.css">
  <link rel="stylesheet" href="css/components.css">
  <!-- /build -->
  
  <!-- build:js js/app.min.js -->
  <script src="js/jquery.js"></script>
  <script src="js/app.js"></script>
  <!-- /build -->
</head>
<body>
  <!-- build:include header.html -->
  <!-- /build -->
  
  <main>
    <!-- build:process echo "Hello, <%= name %>" -->
    <p>Dynamic content will appear here</p>
    <!-- /build -->
  </main>
  
  <!-- build:include footer.html -->
  <!-- /build -->
</body>
</html>

Comments Playground

Experiment with HTML comments in our live editor

Comment Examples Preview

Ready-to-use examples covering different commenting scenarios

Live Preview

Comment Types Included

Basic

Single/multi-line

Development

TODO/FIXME

Sectioning

Document structure

Conditional

Historical reference

All examples will be loaded into an interactive editor where you can modify and test them

< Previous Next >

HTML Comments Guide

Why Use HTML Comments?

Comment Syntax Basics

Single-line Comments

Multi-line Comments

Inline Comments

Commenting Out Code

Practical Uses of Comments

Development Notes

Section Headers

Templating Notes

Browser-Specific Workarounds

Advanced Comment Techniques

Comment-Based Documentation

Build Process Directives

Conditional Comments (Deprecated)

Commenting Best Practices

Clarity Over Quantity

Recommended

Not Recommended

Avoid Redundant Comments

Recommended

Not Recommended

Keep Comments Updated

Recommended

Not Recommended

Security Considerations

Recommended

Not Recommended

Comprehensive Examples

Documenting a Component

Development Workflow

Build Process Integration

Comments Playground

Comment Examples Preview

Comment Types Included