HTML Comments

Introduction

HTML comments (<!-- -->) are parser tokens excluded from the DOM — invisible to users but visible in View Source, DevTools, and server-side scrapers. Conditional comments for IE are dead but still appear in legacy CMS templates. Staff engineers audit comments for secrets, PII, and server-side directive leaks — Shopify theme reviews flag TODO comments with ticket IDs only.

Business problem

Comment leakage exposes internal architecture, API keys in TODO notes, and customer data in HTML templates emailed to browsers. Google caches View Source snapshots; attackers grep public pages for "; nested comments invalid — --> breaks parsing. Comments not inserted into DOM tree — not accessible to querySelector.

• Script edge: for template readability in source — stripped in prod.
• Bad:
• Knockout/Vue legacy: — migrate to modern frameworks.

<!-- Development only — stripped by html-minifier in production -->
<!-- section-start: pricing -->
<section id="pricing">…</section>
<!-- section-end: pricing -->

Accessibility analysis

Comments are invisible to assistive technology — never hide critical content or ARIA fixes only in comments. Some developers "comment out" alt text — image still renders without alt.

• False sense: Commenting broken markup doesn't remove accessibility issue if uncommented later partially.
• Screen readers: No access to HTML comments — use aria-describedby for dev notes in staging only.
• WCAG: Content in comments is not available — fails if intended for users.

SEO impact

Search engines ignore standard HTML comments for ranking — keyword stuffing in comments wasted effort. Hidden text in comments near body doesn't help; deceptive hidden content in comments still risky if exposed by parser bugs.

• Crawl budget: Bloated comment HTML slows download marginally.
• Leaks: Internal link URLs in comments discoverable by competitors scraping source.
• Sitemaps: Comments irrelevant — focus on visible semantic content.

Security considerations

Comments are a secret-leak vector — not protected by CSP or JS. Pen testers grep for TODO, password, key, staging. Amazon security review strips comments from customer-facing HTML builds.

• PII: in error page template.
• Path disclosure:
• Conditional SSI: Injection if server parses user input in comment context — rare but catastrophic.

Performance impact

Comment bytes count toward HTML download. html-minifier in Shopify theme deploy removes comments — measurable savings on large Liquid files.

• Build pipeline: Strip comments in prod, keep in dev source maps of templates.
• CDN: Compressed comments still compress but waste stringify CPU.
• Parser: Tokenizer must skip long comments — minor CPU on huge files.

Real production example

Google production pages ship minified HTML without comments. Stripe docs build removes MDX HTML comments. Shopify Theme Check warns on excessive comment blocks in theme.liquid.

• CI: grep pre-commit hook blocks apiKey patterns in HTML/templates.
• SSR: NODE_ENV=production disables debug comment injection.
• Audit: Quarterly view-source sample of top URLs for comment leaks.

# ci/html-comment-scan.sh
rg -i "(api[_-]?key|password|secret|sk_live)" templates/ && exit 1

Enterprise usage

Enterprise template repos use JSDoc-style ticket references in comments stripped before deploy. SSI comments restricted to ops-owned includes, not author-editable CMS fields.

• Policy: No comments in customer HTML responses — server logs for debug.
• Training: Devs learn commented script != disabled download.
• Tools: html-minifier-terser in webpack/Vite production HTML plugin.

Common production failures

Production HTML contained visible in View Source — cited in security audit; comments banned by policy next day.

• Malformed comment: Uncommented half of script block — XSS from intended "disabled" code.
• SEO myth: Team added keyword comments — no gain, leaked campaign codenames.
• Legal: Commented-out pricing in HTML discovered in discovery — contractual dispute.

Architecture review questions

• Are production HTML responses stripped of developer comments?
• Do comments contain secrets, PII, or internal paths?
• Is "commented out" markup actually removed from DOM, not just hidden?
• Do conditional comments or SSI directives remain in public templates?
• What is HTML size impact of comment blocks on this page?
• Are debug comments gated on non-production environments only?

Hands-on project

Add CI pipeline step to strip HTML comments in production build and fail on secret patterns in templates; audit top 20 URLs view-source post-deploy.

• Deliverable: pre-commit hook + minifier config.
• Verify: curl prod HTML — zero Advanced)

  No positive SEO effect; keywords in comments ignored. AT doesn't read comments — never put user-facing content there. Comments increase HTML size and leak secrets in View Source — strip in production.

  Follow-up: Can Google see comments?

  Security review findings common with HTML comments?(Advanced)

  API keys, internal hostnames, unreleased feature names, admin URLs, and customer emails in TODO comments. Comments transmit to every visitor — treat as public. Automate secret scanning in templates.

  Follow-up: What about server-side includes in comments?

  Does commenting out script in HTML prevent execution?(Advanced)

  Only if properly inside <!-- --> outside script tags, or script content uses JS comment syntax inside script element. Malformed nesting executes. Better: remove script or use build flag — don't rely on comments for security.

  Follow-up: Parser recovery on broken comments?