Comments & Character Entities

This lesson covers two small tools that you will use on almost every page. Comments let you leave notes in your code that the browser does not show. Character entities let you show characters that HTML would otherwise treat as code, such as < and &.

Both are easy to learn, and both hide a trap or two that this lesson will help you avoid.

Writing comments

A comment starts with <!-- and ends with -->. Everything between them is ignored when the page is drawn. A comment can be on one line or across many lines.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Comments</title>
</head>
<body>
  <!-- Header: shop name and tagline -->
  <h1>Aarav Electronics</h1>
  <p>Phones, chargers and repairs in Jaipur.</p>

  <!--
    Diwali offer section.
    Remove after 15 November.
  -->
  <p>Diwali offer: free screen guard with every phone.</p>

  <!-- <p>Old offer: 10% off headphones.</p> -->
</body>
</html>

Comments are useful for three things:

• Explaining why. A short note about a decision helps you, or a teammate, months later.
• Labelling sections of a long file, so you can find your way around.
• Switching code off for a while without deleting it, like the old offer above.

In VS Code, select some lines and press Ctrl+/ (Cmd+/ on a Mac) to wrap them in a comment. Press it again to remove the comment.

Comments are public

A comment is hidden on the page, but it is not secret. Anyone can press Ctrl+U to view the source, or open DevTools, and read every comment you wrote. Never put passwords, private notes about customers, internal prices or anything you would not want a visitor to read in an HTML comment.

Also keep comments short and useful. A comment that just repeats the code, like <!-- paragraph --> above a <p>, adds noise without adding information.

Comments cannot be nested

A comment ends at the first --> the browser finds. So you cannot put one comment inside another:

<!-- Start of disabled block
  <p>Old timings</p>
  <!-- inner note -->
  <p>This paragraph is NOT hidden.</p>
-->

The first -->, at the end of "inner note", closes the whole comment. The last paragraph shows on the page, and the final --> appears as stray text. When you want to disable a block that already contains comments, remove or change the inner comments first.

Why character entities exist

Some characters have a special job in HTML. A < starts a tag, and an & starts an entity. What if you want to show those characters as plain text, for example in a tutorial about HTML?

A character entity (the standard calls it a character reference) is a code that stands for one character. It starts with & and ends with ;. The browser replaces it with the real character.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Entities</title>
</head>
<body>
  <p>Use the &lt;p&gt; element for paragraphs.</p>
  <p>Our shop is called Sharma &amp; Sons.</p>
  <p>Without the entity: <p> disappears, because the browser reads it as a tag.</p>
</body>
</html>

The first paragraph shows <p> as text. In the last line, the <p> you typed is treated as a real tag, so it vanishes from the sentence and starts a new paragraph instead.

The entities you will use most

Numeric references

Every character also has a number in Unicode, the worldwide list of characters. You can write any character with its number, either in decimal &#...; or in hexadecimal &#x...;. For example, the rupee sign is number 8377, which is 20B9 in hexadecimal:

<p>Ticket price: &#8377;350</p>
<p>Ticket price: &#x20B9;350</p>
<p>Ticket price: ₹350</p>

All three lines show the same thing. There is no named entity for the rupee sign, so the numeric form is the only entity choice.

Always escape ampersands

Why bother writing & for a plain &? Because the browser tries to read whatever follows an & as an entity name, and sometimes it succeeds when you did not want it to.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Ampersands</title>
</head>
<body>
  <p>Wrong: shop.example.com/list?size=10&copy=2</p>
  <p>Right: shop.example.com/list?size=10&amp;copy=2</p>
</body>
</html>

In the first line, &copy is the start of the copyright entity, so the browser shows size=10©=2. Writing & every time you mean a literal ampersand avoids this kind of surprise.

The non-breaking space

  is a space that the browser will not use as a line break. Use it to keep two things together on the same line, such as a number and its unit, or a currency sign and an amount: 10 km, ₹ 500, Class 10.

Do not use a row of   entities to indent text or create gaps. That is a layout job, and layout belongs in CSS.

Common mistakes

• Secrets in comments. Comments are visible in the page source. Keep private information out of HTML.
• Nesting comments. The first --> ends the comment, so inner comments break the outer one.
• Forgetting the semicolon. &lt sometimes works without it, but not always. Always end an entity with ;.
• Using   for spacing. Use CSS margin, padding or gap instead.
• Writing a raw & in text. It can turn into an unexpected symbol. Write &.

Key points

• Comments use <!-- and -->; the browser hides them, but anyone can read them in the source.
• Comments cannot be nested; the first --> ends the comment.
• Character entities start with & and end with ;; use <, > and & to show reserved characters.
• Numeric references like ₹ can write any Unicode character, including ₹.
• With UTF-8, most symbols can be typed directly; entities are mainly for reserved characters.
•   keeps words together on one line, but it is not a tool for spacing.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>HTML Tip of the Day</title>
</head>
<body>
  <!-- Daily tip page for our coding club -->
  <h1>Tip of the day</h1>
  <p>Use <code>&lt;strong&gt;</code> for importance and <code>&lt;em&gt;</code> for stress.</p>
  <p>Thanks to Patel &amp; Daughters for printing our posters.</p>
  <p>It was 42&deg;C in Jaipur today, so the club meets indoors.</p>
  <p>Club fee: ₹&nbsp;250 per term.</p>
  <!-- <p>Next tip: tables. Coming soon.</p> -->
</body>
</html>