HTML Comments

Learn to document your code like a professional developer!

What are HTML Comments?

HTML Comments are notes you write in your code that browsers ignore. They're invisible to website visitors but help you and other developers understand the code!

  • Invisible: Don't appear on the webpage
  • Documentation: Explain what your code does
  • Organization: Help structure and label sections
  • Debugging: Temporarily disable code

Think of it like this: Comments are like sticky notes on your code — helpful reminders that only developers can see!

HTML Comment Syntax

Example: Basic Comment


<!-- This is a comment -->

<p>This text appears on the page.</p>

<!-- This comment is invisible to users -->
  • Start with <!--
  • End with -->
  • Everything between is ignored by the browser
  • Can span multiple lines

Remember: Comments start with <!-- and end with -->

Single-Line Comments

Example: Short Comments


<!-- Main navigation menu -->
<nav>
    <a href="index.html">Home</a>
    <a href="about.html">About</a>
</nav>

<!-- Hero section -->
<section class="hero">
    <h1>Welcome!</h1>
</section>

<!-- TODO: Add contact form here -->

Use for: Brief explanations, section labels, and quick reminders

Multi-Line Comments

Example: Longer Explanations


<!-- 
    This is a multi-line comment.
    You can write as much as you want here.
    Great for detailed explanations!
-->

<!--
    ABOUT SECTION
    This section contains information about our company,
    including our mission, vision, and team members.
    Last updated: February 2026
-->
<section id="about">
    <h2>About Us</h2>
</section>

Use for: Detailed descriptions, documentation, and section headers

Organizing Code with Comments

Example: Section Dividers


<!-- ========== HEADER SECTION ========== -->
<header>
    <nav>
        <a href="#">Home</a>
    </nav>
</header>

<!-- ========== MAIN CONTENT ========== -->
<main>
    <h1>Welcome</h1>
</main>

<!-- ========== FOOTER SECTION ========== -->
<footer>
    <p>© 2026 My Website</p>
</footer>

Pro Tip: Use visual separators to make your code easier to navigate!

Temporarily Disabling Code

Example: Commenting Out Elements


<h1>My Website</h1>

<!-- Temporarily hidden while we update it
<p>This paragraph won't show on the page.</p>
<img src="old-banner.jpg" alt="Banner">
-->

<p>This paragraph is visible.</p>

<!-- Old navigation - keeping for reference
<nav>
    <a href="old-page.html">Old Link</a>
</nav>
-->

Use for: Testing changes without deleting code, or keeping old code for reference

TODO and FIXME Comments

Example: Task Reminders


<!-- TODO: Add search functionality -->
<nav>
    <a href="index.html">Home</a>
</nav>

<!-- FIXME: This image is broken -->
<img src="broken-link.jpg" alt="Image">

<!-- NOTE: This section needs review before launch -->
<section>
    <h2>Beta Feature</h2>
</section>
  • TODO: Tasks to complete later
  • FIXME: Code that needs fixing
  • NOTE: Important information
  • HACK: Temporary workaround

Inline Comments

Example: Comments Next to Code


<img src="logo.png" alt="Company Logo"> <!-- Updated logo 2026 -->

<a href="contact.html">Contact</a> <!-- Links to contact form -->

<div class="container"> <!-- Max width: 1200px -->
    <p>Content here</p>
</div>

Tip: Keep inline comments short and to the point!

Comment Best Practices

Example: Good vs Bad Comments


<!-- ❌ BAD: Obvious comment -->
<p>Welcome</p> <!-- This is a paragraph -->

<!-- ✅ GOOD: Explains WHY -->
<p>Welcome</p> <!-- Shown to first-time visitors only -->

<!-- ❌ BAD: Outdated comment -->
<!-- Contact form goes here (actually removed in 2025) -->

<!-- ✅ GOOD: Up-to-date and helpful -->
<!-- Contact section - form replaced with email link -->

<!-- ❌ BAD: Too vague -->
<div></div> <!-- Important stuff -->

<!-- ✅ GOOD: Specific and clear -->
<div></div> <!-- Container for featured products carousel -->
  • Explain WHY, not just WHAT
  • Keep comments up-to-date
  • Don't state the obvious
  • Be clear and specific
  • Use proper grammar and spelling

What NOT to Comment

Example: Unnecessary Comments


<!-- ❌ AVOID: Obvious statements -->
<h1>Title</h1> <!-- This is a heading -->
<a href="#">Link</a> <!-- This is a link -->

<!-- ❌ AVOID: Redundant information -->
<!-- Navigation bar with links -->
<nav>
    <a href="home.html">Home</a>
    <a href="about.html">About</a>
</nav>

<!-- ✅ BETTER: Only comment when necessary -->
<!-- Sticky navigation - remains visible on scroll -->
<nav class="sticky">
    <a href="home.html">Home</a>
    <a href="about.html">About</a>
</nav>

Golden Rule: If the code is self-explanatory, you don't need a comment!

Comments Cannot Be Nested

Example: Nested Comments Don't Work


<!-- ❌ WRONG: Nested comments break -->
<!--
    Outer comment
    <!-- Inner comment -->
    This won't work correctly!
-->

<!-- ✅ CORRECT: Use one comment block -->
<!--
    If you need to comment out code with comments,
    remove the inner comments first or rewrite them.
-->

Important: HTML doesn't support nested comments — avoid putting comments inside comments!

Real-World Example

Example: Well-Commented HTML Page


<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>My Portfolio</title>
</head>
<body>

    <!-- ========== HEADER ========== -->
    <header>
        <!-- Logo and site title -->
        <h1>John Doe</h1>
        
        <!-- Main navigation -->
        <nav>
            <a href="#about">About</a>
            <a href="#projects">Projects</a>
            <a href="#contact">Contact</a>
        </nav>
    </header>

    <!-- ========== MAIN CONTENT ========== -->
    <main>
        <!-- Hero section with introduction -->
        <section id="hero">
            <h2>Welcome to My Portfolio</h2>
            <p>Web Developer & Designer</p>
        </section>

        <!-- About section -->
        <section id="about">
            <h2>About Me</h2>
            <p>I create beautiful websites.</p>
        </section>

        <!-- TODO: Add project gallery here -->
        
    </main>

    <!-- ========== FOOTER ========== -->
    <footer>
        <p>© 2026 John Doe</p>
    </footer>

</body>
</html>

Security Warning

Example: What NOT to Put in Comments


<!-- ❌ NEVER: Put sensitive information in comments -->
<!-- Database password: mySecretPass123 -->
<!-- API Key: sk_live_abc123xyz789 -->
<!-- Admin login: admin@example.com -->

<!-- ✅ SAFE: Generic, non-sensitive comments -->
<!-- Contact form connects to backend API -->
<!-- User authentication handled server-side -->

Critical: Comments are visible in page source — never include passwords, API keys, or private information!

Best Practices Summary

  • Use comments to explain complex or unclear code
  • Label major sections of your HTML
  • Keep comments concise and relevant
  • Update comments when you change code
  • Remove unnecessary or outdated comments
  • Never include sensitive information
  • Use TODO/FIXME for tasks and bugs
  • Don't over-comment obvious code

Remember: Good comments make your code easier to understand and maintain!