HTML Comments

Comments help you document your code, leave notes for other developers, and temporarily disable content. They’re not visible to users.

Basic Syntax

Comments start with :

<!-- This is a comment -->
<p>This paragraph is visible.</p>
<!-- This paragraph is hidden -->
<p>This paragraph is also visible.</p>

Multi-Line Comments

Comments can span multiple lines:

<!--
  This is a multi-line comment.
  It can span as many lines as you need.
  Great for detailed explanations.
-->

Common Use Cases

Documenting Code

Explain complex sections:

<!-- Hero Section -->
<!-- This section uses a background image and overlay -->
<section class="hero">
  <h1>Welcome to My Site</h1>
</section>

<!-- Navigation Menu -->
<!-- Uses dropdown menus for mobile -->
<nav>
  <!-- Main menu items -->
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
  </ul>
</nav>

Temporarily Disabling Content

Comment out code you want to keep but not display:

<p>Visible paragraph</p>

<!--
<p>This paragraph is commented out and won't show.</p>
<img src="old-image.jpg" alt="Old image" />
-->

<p>Another visible paragraph</p>

TODO Notes

Remind yourself or others to do something later:

<!-- TODO: Add form validation -->
<form>
  <input type="email" name="email" />
</form>

<!-- TODO: Update this image when new design is ready -->
<img src="placeholder.png" alt="Coming soon" />

Fixme Notes

Mark code that needs immediate attention:

<!-- FIXME: This layout breaks on mobile -->
<div class="sidebar">
  <!-- Content here -->
</div>

<!-- HACK: Temporary workaround for bug #123 -->
<div style="margin-top: 10px;">
  <!-- Content here -->
</div>

Section Markers

Divide large files into logical sections:

<!DOCTYPE html>
<html>
  <head>
    <!-- ========== META TAGS ========== -->
    <meta charset="UTF-8" />
    <title>My Site</title>

    <!-- ========== STYLES ========== -->
    <link rel="stylesheet" href="styles.css" />
  </head>
  <body>
    <!-- ========== HEADER ========== -->
    <header>
      <!-- Navigation -->
      <nav></nav>
    </header>

    <!-- ========== MAIN CONTENT ========== -->
    <main>
      <!-- Hero Section -->
      <section class="hero"></section>

      <!-- Features Section -->
      <section class="features"></section>
    </main>

    <!-- ========== FOOTER ========== -->
    <footer></footer>

    <!-- ========== SCRIPTS ========== -->
    <script src="app.js"></script>
  </body>
</html>

Conditional Comments (Legacy)

Old IE browsers supported these (not standard):

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

Note: Don’t use these in modern code.

Complete Example

Here’s a complete page with well-commented code:

<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- Character encoding and viewport -->
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <!-- SEO Meta Tags -->
    <title>My Portfolio</title>
    <meta name="description" content="Web developer portfolio" />

    <!-- Stylesheets -->
    <link rel="stylesheet" href="css/main.css" />
  </head>
  <body>
    <!-- ========================================
         HEADER & NAVIGATION
         ======================================== -->
    <header>
      <nav aria-label="Main navigation">
        <ul>
          <li><a href="/">Home</a></li>
          <li><a href="/projects">Projects</a></li>
          <li><a href="/contact">Contact</a></li>
        </ul>
      </nav>
    </header>

    <!-- ========================================
         MAIN CONTENT
         ======================================== -->
    <main>
      <!-- Hero Section -->
      <!-- Displays intro text with call-to-action -->
      <section class="hero">
        <h1>Hello, I'm a Web Developer</h1>
        <p>I build modern, accessible websites.</p>
        <a href="/projects" class="btn">View My Work</a>
      </section>

      <!-- Projects Grid -->
      <!-- TODO: Add filtering by category -->
      <section class="projects">
        <h2>Featured Projects</h2>
        <div class="grid">
          <!-- Project Card 1 -->
          <article class="card">
            <img src="project1.jpg" alt="Project 1" />
            <h3>E-commerce Site</h3>
            <p>Built with React and Node.js</p>
          </article>

          <!-- Project Card 2 -->
          <!-- FIXME: Image needs optimization -->
          <article class="card">
            <img src="project2.jpg" alt="Project 2" />
            <h3>Blog Platform</h3>
            <p>Built with Next.js</p>
          </article>
        </div>
      </section>
    </main>

    <!-- ========================================
         FOOTER
         ======================================== -->
    <footer>
      <p>&copy; 2026 My Portfolio. All rights reserved.</p>

      <!-- Social Links -->
      <div class="social">
        <a href="https://github.com/me" aria-label="GitHub">GitHub</a>
        <a href="https://linkedin.com/in/me" aria-label="LinkedIn">LinkedIn</a>
      </div>
    </footer>

    <!-- Scripts -->
    <script src="js/main.js"></script>
  </body>
</html>

Best Practices

Be consistent — Use the same comment style throughout
Keep comments updated — Remove or update outdated comments
Comment the why, not the what — Explain reasoning, not obvious code
Use section markers — Divide large files into logical sections
Remove before production — Don’t ship unnecessary comments

Common Mistakes

Over-commenting — Obvious code doesn’t need comments
Outdated comments — Comments that contradict the code
Missing comments — Complex code should be documented
Nested comments —  --> doesn’t work
Secrets in comments — Never put passwords or API keys in comments