HTML Comments (Best Practices)

HTML Comments (Best Practices)

HTML comments let you add notes directly in your source code that are completely invisible to website visitors but visible to anyone viewing the page source — making them an essential tool for documentation, team collaboration, and debugging.

Comment Syntax

Anything between <!-- and --> is ignored by the browser and not rendered on the page.

Common Use Cases for Comments

• Documentation — explaining why a section of code exists or how it works.
• Section markers — labeling large sections of a page for easier navigation in long files.
• Debugging — temporarily "commenting out" code to test without deleting it.
• Team collaboration — leaving TODO notes or instructions for other developers.

Commenting Out Code

Best Practices for Writing Comments

• Comment on why something exists, not just what it does — the code already shows what it does.
• Keep comments up to date; outdated comments are worse than no comments.
• Avoid leaving sensitive information (API keys, internal notes, credentials) in comments — they are publicly visible in page source.
• Don't over-comment obvious code — use comments strategically for complex or non-obvious sections.
• Remove large blocks of commented-out "dead code" before deploying to production.

A Security Note (Important, Often Overlooked)

Because HTML comments are visible to anyone who views your page source, never include sensitive data, internal URLs, or credentials inside them — this is a surprisingly common real-world security mistake.

Key Takeaways

• HTML comments use <!-- comment --> syntax and are invisible on the rendered page.
• Use comments for documentation, section labeling, and temporary debugging.
• Never store sensitive data in comments — they're visible in page source.
• Clean up unused commented-out code before shipping to production.