CSS Comments

Two slashes start a comment in JavaScript and many other languages, but in CSS a line that starts with // is not a comment at all. The browser reads it as the start of a broken rule and silently throws away the rule that follows it. CSS has exactly one comment syntax, and knowing how the browser reads it explains both what comments can do and how they go wrong.

How a CSS Comment Works

A comment is text in a style sheet that the browser ignores completely. It starts with /* and ends with the next */, and everything between the two markers, including line breaks, is skipped:

/* This is a CSS comment */

A comment can go anywhere a space could go: between two rules, between two declarations, at the end of a declaration on the same line, or across many lines. It has no effect on the page. However, it is not hidden from visitors. Comments stay in the CSS file that every visitor downloads, and anyone can read them with the browser's developer tools, so never put passwords, private notes or internal addresses in them.

Comments in the Book Club Style Sheet

Here is the book club page with its style sheet commented. It uses each common kind of comment once:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Book Club</title>
  <style>
    /* ==========================================
       Book club site styles
       Colors: darkgreen for brand, dimgray for text
       ========================================== */

    /* Page */
    body {
      margin: 0;
      font-family: Georgia, serif;
      background-color: linen;
      color: dimgray;
    }

    /* Header and navigation */
    header {
      background-color: darkgreen;
      color: white;
      padding: 16px;
    }

    nav a {
      color: white; /* links default to blue, which is unreadable on darkgreen */
      margin-right: 16px;
    }

    /* Buttons */
    .button {
      background-color: darkgreen;
      color: white;
      border: none;
      padding: 10px 20px;
      /* border-radius: 4px; */
    }
  </style>
</head>
<body>
  <header>
    <h1>Monthly Book Club</h1>
    <nav>
      <a href="#">Home</a>
      <a href="#">Books</a>
    </nav>
  </header>
  <main>
    <p>Join us on the first Friday of every month to talk about one book.</p>
    <button class="button">Reserve a seat</button>
  </main>
</body>
</html>

The page renders exactly as it would without any of the comments. Each comment does a different job, though.

A header comment at the top spans several lines and records decisions that apply to the whole file, here the two main colors. The lines of = signs are only decoration that makes the block easy to spot.

Section comments, such as /* Header and navigation */, mark where each part of the file begins. In a long file, they let a reader jump to the right place by searching for the section name.

An end-of-line comment after color: white; explains why the declaration exists. Without the rule, the browser draws links in its default blue, rgb(0, 0, 238), which is hard to read on a dark green background. The code already shows that the color is white; the comment adds the reason, which the code cannot show.

A commented-out declaration, /* border-radius: 4px; */, turns a declaration off without deleting it. The browser skips it, so the button keeps square corners (its computed border-radius is 0px), while the other four declarations in the rule still apply. This is useful while you test a change. Once you decide, delete the line, because a file full of switched-off code is hard to read.

Comments also work inside a style attribute, because the attribute holds ordinary declarations. The attribute style="color: navy; /* sale banner */ font-size: 20px" still gives the element navy text at 20px.

Two Ways a Comment Breaks a Rule

Both mistakes below remove a rule without any error message, so they are worth recognizing.

Using // for a comment. Consider this style sheet:

// Heading color
h1 {
  color: darkgreen;
}

p {
  color: navy;
}

The paragraph turns navy, but the heading stays black. The browser does not treat // as a comment, so it reads // Heading color h1 as the selector of a rule. That selector is invalid, so the browser drops the whole rule, including the color: darkgreen declaration meant for the heading. The p rule after it is read normally. Replace the line with /* Heading color */ and the heading turns dark green.

Putting one comment inside another. CSS comments cannot be nested, because a comment ends at the first */ the browser finds:

/* Old heading rule:
   /* h1 { color: crimson; } */
   Remove after launch.
*/
h1 {
  color: darkgreen;
}

p {
  color: navy;
}

The writer meant the whole first block to be one comment. However, the comment ends at the */ on the second line. The words Remove after launch. and the stray */ are then read as CSS, and they join with h1 to form one invalid selector. As a result, the h1 rule is dropped, and the heading stays black, while the paragraph is navy. To comment out code that already contains a comment, remove the inner comment markers first.