HTML comments: syntax, useful notes, and what they do not hide

HTML comments begin with <!-- and end with -->. They are not rendered as page text, but remain in the delivered source. Use them to explain a decision that the surrounding markup cannot explain.

Inspect a comment beside real content

The note appears in the copied source but not in the preview’s visible paragraph. Open the standalone document’s source or developer tools to find the comment node.

<!-- Keep this explanation visible when CSS is unavailable. -->
<p>The example works without a script.</p>

p {
  padding: 0.75rem;
  border-inline-start: 4px solid #2563eb;
}

Explain why, rather than repeating the tag

A useful comment might record why a navigation label differs from a product name, or link to the reason a compatibility workaround remains. “This is a paragraph” beside p adds little. Keep the note close to the relevant code and update or remove it when the decision changes.

HTML comments are not CSS comments or JavaScript comments. Inside style/script, use the language’s own comment syntax. Do not nest HTML comments or place invalid comment delimiters inside them. A comment between elements is safe for this exercise; comments cannot be inserted into a tag’s attribute list as if they were whitespace.

Comments are not access control

Comments can temporarily remove ordinary markup from rendering during local editing, but anything sent to the browser can be read. CSS display:none also does not protect private information. Enforce authorization before sending protected content. Keep secrets, internal credentials, and private data out of delivered comments.

Prefer version control to a growing archive of commented-out code. There is no need for a universal comment-length rule or a preconnect added merely because a comment says it improves performance: measure the actual dependency first.

What about search?

Search engines can receive the source, so “comments are invisible to search engines” is inaccurate. Comments are not a useful place to put ranking keywords or reader instructions. Put useful explanations in visible content and metadata in the appropriate head elements.

Learn CSS comments, version control, and the head element.

Sources

Reference 1 provide the technical details and current compatibility information.