CSS Comments

A CSS comment is text inside a stylesheet that the browser’s CSS parser completely ignores when rendering a page. Comments exist purely for humans: they let you explain why a rule exists, temporarily disable a declaration while testing, or divide a long stylesheet into readable sections. Understanding exactly how comments are parsed — and where they can and cannot go — will save you from some surprisingly confusing bugs.

Overview / How it works

Every CSS parser processes a stylesheet as a stream of characters, and one of the very first things it does is strip out anything wrapped in /* and */ before it even tries to interpret selectors, properties, or values. This means a comment is not a CSS “statement” the way a rule or a declaration is — it is closer to whitespace. The parser treats an entire comment block, no matter how long, as if it were a single space character. That has an important consequence: a comment can be inserted almost anywhere in a stylesheet without breaking anything, as long as it does not split a token (like a property name or a hex color) in half.

Because comments are discarded before layout and rendering even begin, they have zero effect on the box model, the cascade, specificity, or performance at runtime (browsers parse the CSS once; the comment text is not re-processed every frame). Their only “cost” is a few extra bytes downloaded over the network, which is why production build tools often strip comments out during minification — that optimization is invisible to your users either way, since comments never affected rendering in the first place.

CSS has exactly one comment syntax. Unlike JavaScript, CSS does not support a single-line // comment. If you write // like this in a stylesheet, the browser will not treat it as a comment — it will try to parse // as an invalid selector or value and silently ignore that malformed chunk, which is a common source of confusion for developers coming from JS.

Syntax

The general form of a CSS comment is:

/* any text, including
   multiple lines, goes here */
  • /* — opens the comment. Everything after this is ignored by the parser.
  • the comment body — any characters at all, including line breaks, other punctuation, and even CSS-looking syntax. None of it is interpreted.
  • */ — closes the comment. This is required; a comment that never closes swallows the rest of the file.

Comments can appear between rules, inside a declaration block, or even in the middle of a single declaration (though that last option hurts readability and should be avoided). They cannot be nested — the first */ the parser finds closes the comment, no matter how many /* sequences appear before it.

Examples

Example 1: Documenting a rule

/* Primary call-to-action button used across the marketing site */
.btn-primary {
  background-color: #2563eb;
  color: #ffffff;
  padding: 0.75rem 1.5rem;
  border-radius: 0.375rem;
}

Result: The button is styled exactly as if the comment were not there — a blue rectangle with white text and rounded corners. The comment produces no visual change; it only leaves a note in the source explaining what the rule is for.

This is the most common use of comments: labeling a rule so that anyone reading the stylesheet later (including future you) understands its purpose without having to reverse-engineer it from the selector name alone.

Example 2: Temporarily disabling a declaration

.card {
  border: 1px solid #d1d5db;
  /* box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1); */
  padding: 1rem;
}

Result: The card renders with a thin gray border and padding, but no drop shadow, because the box-shadow declaration has been “commented out” and is skipped entirely by the parser.

This is an everyday debugging technique: instead of deleting a line you might want back, wrap it in /* */. The declaration stays in the file for reference but has no effect until you remove the comment markers.

Example 3: Sectioning a larger stylesheet

/* ==========================================================================
   Layout
   ========================================================================== */

.container {
  max-width: 1200px;
  margin-inline: auto;
  padding-inline: 1rem;
}

/* ==========================================================================
   Typography
   ========================================================================== */

h1, h2, h3 {
  font-family: "Georgia", serif;
  line-height: 1.2;
}

Result: The page renders with a centered, max-width container and serif headings with tight line spacing. The banner-style comments produce no visual output at all — they exist purely to make the file easier to navigate when you scroll through it in an editor.

In large, hand-maintained stylesheets, this kind of visual section banner is extremely common because it lets a developer jump straight to the “Layout” or “Typography” block instead of reading line by line.

How it works step by step / Under the hood

  • Tokenizing: The CSS parser scans the raw text character by character looking for tokens (selectors, braces, property names, colons, values, semicolons).
  • Comment detection: The moment the tokenizer sees the two characters /*, it switches into “comment mode” and stops trying to interpret anything as CSS syntax.
  • Skipping: Every character — including newlines, braces, and even things that look like real declarations — is consumed and discarded until the tokenizer finds the matching */.
  • Resuming: Once */ is found, the tokenizer resumes normal parsing exactly as if the comment text had been a single blank space.
  • No re-nesting: Because the tokenizer just looks for the next */, it has no concept of “nested” comments. The first closing marker always wins.

This single-pass, state-machine behavior is why comments are so predictable: the parser never tries to make sense of what is inside them, so you can put anything there — including notes, old code, or ASCII art — without risking a syntax error, as long as the comment itself is properly opened and closed.

Common Mistakes

Mistake 1: Using JavaScript-style single-line comments

// This is NOT a valid CSS comment
color: red;

CSS has no // comment syntax. A line like this is not ignored — the parser tries to read // as the start of a selector or declaration, fails, and typically discards that whole malformed statement, silently dropping any real CSS that follows on the same line. The fix is to always use the block syntax:

/* This is a valid CSS comment */
color: red;

Mistake 2: Attempting to nest comments

/* outer comment /* inner comment */ still outside? */

Because the parser closes the comment at the first */ it encounters, this actually closes after “inner comment”, leaving the trailing text still outside? */ to be parsed as real CSS — which will likely produce an invalid declaration or selector. Never rely on nested /* */ pairs; if you need to comment out a block that already contains comments, remove or rewrite the inner comments first, or comment out each declaration individually.

Best Practices

  • Use comments to explain why a rule exists (a browser workaround, a design decision, a dependency on other CSS) rather than restating what the property obviously does.
  • Use a consistent banner style for major sections in long stylesheets so they are easy to scan visually.
  • Comment out code you are debugging instead of deleting it, so you can quickly restore it if needed.
  • Remove stale or outdated comments during code review — a wrong comment is worse than no comment because it actively misleads the next reader.
  • Let your build tool (a bundler or minifier) strip comments for production output; keep them in your source files for maintainability.
  • Avoid comments in the middle of a single declaration (e.g. between a property and its value) — it hurts readability even though it is technically valid.

Practice Exercises

  • Exercise 1: Write a CSS rule for a .warning-box class with a yellow background and a comment above it explaining that it is used for non-critical alert messages.
  • Exercise 2: Take a rule with three declarations (e.g. margin, font-size, text-align) and comment out just the middle one so the other two still apply. Predict what the element will look like with only two of the three declarations active.
  • Exercise 3: Given a stylesheet with several unrelated rules, add section-banner comments to group them into “Header”, “Main Content”, and “Footer” sections without changing any of the actual styling.

Summary

  • CSS comments use the syntax /* ... */; there is no single-line // comment in CSS.
  • Comments are stripped out during parsing, before layout or rendering, so they never affect the cascade, specificity, or the box model.
  • Comments can span multiple lines and appear almost anywhere in a stylesheet, but they cannot be nested — the first */ closes the comment.
  • Common uses include documenting the purpose of a rule, temporarily disabling declarations while debugging, and visually sectioning large stylesheets.
  • Minifiers typically strip comments for production, so use them freely in source files without worrying about performance.