HTML Comments

Syntax, and What a Comment Really Is

A comment starts with <!-- and ends with -->. Everything between the two is ignored by the browser when it builds the page — it produces no text, no space, no element. A comment can be one line or span twenty, and it can sit anywhere between elements.

The word "ignored" needs one important qualification. The comment is ignored when the page is rendered, not when it is sent. Your comments are downloaded to the visitor's computer along with everything else and are sitting there in the page source for anyone who presses Ctrl+U. They are invisible on the page, not private. That distinction turns out to matter a great deal, and the next section is about it.

There is one place a comment may not go: inside a tag. <p <!-- note -->> is invalid, and the browser will make a mess of it. Comments go between elements or inside an element's content, never in the middle of an opening tag's attributes.

<!-- A single-line comment -->

<!--
  A longer note, spread over
  several lines. None of this
  appears on the page.
-->

<h1>Techfest 2026</h1>

<!-- <p>This paragraph is switched off and will not display.</p> -->

<p>This one will.</p>

<!-- Invalid: a comment cannot sit inside a tag -->
<p <!-- class goes here --> class="intro">Text</p>

Everything You Write in a Comment Is Public

This is the part of the lesson that actually matters, and it is skipped by most tutorials. Anyone can read your comments. Right-click, View Page Source, and every note you left is there in plain text. Search engines crawl them. Automated scanners looking for vulnerable sites read them specifically, because comments are where developers habitually leave useful information behind.

What ends up in comments on real sites, left there by accident, is remarkably consistent. Test usernames and passwords, left over from development. Database names and internal server addresses. Notes such as "remove this before launch, the check is not working yet". Links to admin pages. Internal client names and pricing. Any of these hands a stranger a starting point.

The rule to adopt from today is straightforward: write comments as though a stranger will read them, because one might. Notes that are genuinely private — anything about credentials, security, unreleased plans, or a colleague's work — belong in your project's issue tracker or a document, not in a file you publish. If you would not print it on the page, do not put it in a comment.

The same logic applies to commented-out code. Leaving an old version of a form or a half-built feature commented out in a live page publishes it. It is also dead weight that confuses whoever reads the file next. Version control keeps your history for you — delete the old code and let git remember it.

<!-- All of these have appeared on real, live websites -->

<!-- TODO: the login check is disabled while we test. Fix before launch! -->

<!-- admin panel: /admin-2019/index.php  user: admin  pass: admin123 -->

<!-- database: projectdb on 10.0.4.19 -->

<!-- Client hasn't paid yet, keeping the old prices here just in case:
     Basic 4999, Pro 9999 -->

<!-- Safe, useful comments look like this instead -->

<!-- Contact form posts to the handler in /api/. Do not change the
     field names without updating that file too. -->

• Never put credentials, keys or tokens in a comment, even temporarily
• Never describe a known security weakness in a comment
• Do not leave internal notes about clients, pricing or unreleased features in published files
• Delete commented-out code before you deploy; version control is where old code belongs
• Assume every comment will be read by someone you did not expect
• Keep genuinely private notes in your issue tracker or documentation instead

What Is Worth Commenting

The most common beginner mistake with comments is explaining what the code obviously does. <!-- This is a heading --> above an <h1> adds nothing; anyone reading the file can see it is a heading. HTML is unusually readable already, so a comment has to earn its place.

Good comments explain why, not what. Why is this hidden field here? Why must these two class names stay together? Why is this section duplicated? Those are the questions you will have in three months, and the answers exist nowhere in the code.

The other genuinely useful kind is structural. In a long file, a comment banner marking the start of each major region makes it navigable, and a short comment on a closing tag tells you what it closed. In a wall of </div> tags, <!-- /.card-grid --> is the difference between confidently deleting the right one and breaking your layout.

Keep comments close to what they describe, and update them when you change the code. A comment that no longer matches is worse than no comment, because it is confidently wrong and people trust it.

<!-- ============================================
     MAIN NAVIGATION
     ============================================ -->
<nav aria-label="Main">
  ...
</nav>

<!-- Explains WHY, which the code cannot -->
<input type="hidden" name="source" value="campus-poster">
<!-- Set from the QR code on the printed posters so we can tell
     which campaign a registration came from. -->

<div class="card-grid">
  <article class="card">...</article>
  <article class="card">...</article>
</div><!-- /.card-grid -->

<!-- Useless: says exactly what the next line already says -->
<!-- This is the main heading -->
<h1>Techfest 2026</h1>

• Explain why something is written the way it is, not what it plainly is
• Mark the major regions of a long file so it can be scanned
• Label closing tags where nesting is deep
• Record anything surprising — a workaround, a dependency on another file, an ordering that matters
• Update or delete a comment when you change what it describes

Debugging by Commenting Out

Comments are a debugging tool as much as a documentation tool. When a page looks wrong and you cannot see why, comment out half of the body and reload. If the problem disappears, it is in the half you removed; if it stays, it is in the other half. Repeat on whichever half contains the problem, and you narrow a five-hundred-line file to the offending element in a handful of steps.

There is one restriction that catches people out during this: comments cannot be nested. The very first --> the browser meets ends the comment, no matter how many <!-- came before it. So if you comment out a block that already contains a comment, the outer comment ends early, and the rest of your block reappears on the page along with a stray --> as visible text. When something you thought you had switched off is still showing, look for a comment inside it.

It is also wise to avoid double hyphens inside comment text, since the sequence is what terminates them and older tools treat it as an error. Use a single hyphen, or an equals sign, for decorative separators.

Finally, remember that each language has its own comment syntax. HTML uses <!-- -->. CSS uses /* */ only. JavaScript uses // for one line and /* */ for several. Using HTML's syntax inside a <style> or <script> block is a common slip when you are switching between files.

<!-- Comments do not nest: this ends at the FIRST --> -->

<!-- Trying to switch off a block that already has a comment
<div class="card">
  <!-- card title -->
  <h3>Line-following robot</h3>
</div>
-->
<!-- The outer comment ended at the inner one's -->, so the
     heading below it renders, and a stray arrow appears as text. -->

/* CSS uses this syntax, and only this */
.card { padding: 16px; }

// JavaScript, one line
/* JavaScript, several lines */