Using Comments for Code Documentation

Technical Deep Dive & Specifications

1. Professional Component Documentation Standards

In enterprise frontend engineering, HTML comments should explain why something exists, not restate what the tag already says.

Bad Documentation vs. Good Documentation:

<!-- BAD: Restating the obvious (zero added value) -->
<!-- This is a div with class container -->
<div class="container">
  <!-- This is the heading -->
  <h1>Products</h1>
</div>

<!-- GOOD: Communicating architectural intent, dependencies, and business rationale -->
<!-- =========================================================================
     COMPONENT: ProductGrid
     DATA SOURCE: Ingested from GraphQL query GetCatalogProducts ($limit: 24)
     A11Y REQUIREMENT: Focus trap handled by /assets/js/modules/focus-trap.js
     ========================================================================= -->
<section class="product-grid" aria-labelledby="catalog-heading">
  <h2 id="catalog-heading">Spring Collection</h2>
  <!-- Dynamic product cards populated by client hydrate -->
</section>

2. Documenting Non-Obvious Accessibility (A11Y) Choices

Accessibility implementations often require non-intuitive attribute combinations. Documenting them prevents junior developers or future maintainers from accidentally deleting critical ARIA attributes during refactors:

<!-- 
  NOTE ON A11Y:
  role="status" and aria-live="polite" are placed on the parent container
  BEFORE dynamic alert messages are inserted by JavaScript. Moving these 
  attributes directly to the injected child prevents VoiceOver / NVDA from 
  announcing dynamic state changes!
-->
<div id="live-region" role="status" aria-live="polite" aria-atomic="true">
  <!-- Dynamic status text inserted via JS -->
</div>

3. Server-Side Comments vs. Client-Side HTML Comments

Modern web stacks use server-side templating engines (e.g. Next.js/React JSX, Laravel Blade, Django/Jinja2, Rails ERB, or Svelte). It is critical to understand which syntax is stripped by the server before reaching the client:

  Developer writes:
  -------------------------------------------------------------
  {# DEV ONLY: Internal staging endpoint: https://qa-db.internal #}
  <!-- Section: User Profile Card -->
  <div class="profile-card">Jane Doe</div>

  Server compiles and outputs to Browser:
  -------------------------------------------------------------
  <!-- Section: User Profile Card -->
  <div class="profile-card">Jane Doe</div>
  (Notice the {# ... #} server comment was completely erased!)

4. Security Hygiene: The Top Leaks in HTML Comments

Security penetration testers (and malicious hackers) always scrape HTML comments on target websites. The following data must NEVER appear in HTML comments:

  +-------------------------------------------------------------------------------+
  |                     PROHIBITED IN HTML COMMENTS (CRITICAL)                    |
  +-------------------------------------------------------------------------------+
  | ❌ Hardcoded passwords, API keys, tokens, or JWT secrets                       |
  | ❌ Internal staging/QA URLs (e.g., https://staging-admin.internal.corp)       |
  | ❌ Unreleased feature flags or secret launch dates                            |
  | ❌ Database column names, SQL schema queries, or ORM object structures        |
  | ❌ Employee full names, internal emails, or IT workstation hostnames          |
  | ❌ Detailed stack traces or backend error dumps                               |
  +-------------------------------------------------------------------------------+

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Line 18–22 (<!-- ===== ... MODULE: Multi-Factor Authentication ... ===== -->): Professional enterprise header explaining compliance standards and accessibility links.
• Line 30–33 (<!-- inputmode="numeric" ... autocomplete="one-time-code" ... -->): High-value technical comment explaining non-obvious mobile optimization attributes (inputmode and autocomplete).
• Line 40 (aria-describedby="code-hint"): Connects the input field to its assistive text for screen reader users.

Expected Browser Render Output

Two-Step Verification
Enter the 6-digit security code generated by your authenticator app.

Verification Code
[ ____________________ ]
Enter 6 numbers without spaces.

[ Verify Identity ]