CSS Comments

Sometimes the most useful line in a stylesheet isn't CSS at all, it's a note left for whoever reads the code next (often your future self). That's exactly what CSS comments are for. A CSS comment starts with a forward slash and asterisk, and ends with an asterisk and forward slash. Anything between those markers is completely ignored by the browser, so you can use comments to explain tricky decisions, label sections of a long stylesheet, or temporarily disable a rule while testing. On a real project like cookiescursor.com, a few well-placed comments can save a lot of confusion months later when someone (maybe you) has to update the CSS again.

In this page:

Why Comment CSS
Comment Syntax
Commenting Out Code Temporarily
Multi-line Comments
Comment Best Practices

Why Comment CSS

As a stylesheet grows, it becomes easy to forget why a particular rule exists. Comments capture that context directly in the code, right where future readers will need it. A well-placed comment can save a future developer, including your future self, from re-deriving the same reasoning from scratch.

Note: Write a comment explaining why, not what, the CSS itself already shows what a rule does.

Warning: A stylesheet with zero comments can be genuinely difficult to safely edit months later, even for the person who originally wrote it.

Example: Why Comment CSS

css

/* Fixes a Safari flexbox gap bug -- see issue #482 */
.container {
  gap: 16px;
}

Comment Syntax

A CSS comment always starts with /* and ends with */. Anything written between those two markers, even across multiple lines, is completely ignored when the page renders. Unlike some languages, CSS has no single-line comment syntax, so even a one-line note needs the full slash-star wrapper.

Note: Most code editors let you comment out a selected block of CSS with a keyboard shortcut, no need to type the markers by hand every time.

Warning: CSS does not support // as a comment marker, that syntax belongs to other languages like JavaScript, not CSS.

Example: Comment Syntax

css

/* This is a CSS comment, it can span
   multiple lines */
p {
  color: blue;
}

Commenting Out Code Temporarily

Wrapping an existing declaration in /* */ turns it off without deleting it, which is a fast way to test how a page looks without a particular style. This is a fast, non-destructive way to debug a layout issue before deciding whether to remove the rule permanently.

Note: Comment out a suspicious rule while debugging a layout issue, it's often the quickest way to confirm which rule is actually causing the problem.

Warning: Remember to remove or restore commented-out code once you're done testing, leftover disabled rules make a stylesheet confusing to read later.

Example: Commenting Out Code Temporarily

css

p {
  color: blue;
  /* background: yellow; */
}

Multi-line Comments

Because a CSS comment simply runs from /* to */, it can span several lines just as easily as one, which makes it useful for longer explanations or section headers. This is especially useful for labeling major sections of a large stylesheet, like '/* Navigation styles */'.

Note: Use a multi-line comment as a visual section header to break a long stylesheet into clearly labeled parts.

Warning: A very long, unclosed comment can accidentally swallow rules you meant to keep active, always double-check the closing */.

Example: Multi-line Comments

css

/*
  Navigation styles
  Used across every page in the site
*/
nav {
  display: flex;
}

Comment Best Practices

Good CSS comments are short, focused, and explain something the code alone can't, like a business reason, a browser quirk, or a warning not to remove something. Overly obvious comments that just restate the selector name add clutter without adding any real value.

Note: If you find yourself explaining what a property does, consider whether the comment is really needed, focus comments on the why instead.

Warning: Outdated comments that no longer match the code they describe are worse than no comment at all, since they actively mislead the next reader.

Example: Comment Best Practices

css

/* Bad: restates the obvious -- sets color to red */
p {
  /* Good: explains why -- matches brand red from the style guide */
  color: red;
}

Common Mistakes

Using double-slash comments (//) from other languages, which are not valid in standard CSS.
Forgetting to close a comment with */, which can accidentally comment out a large chunk of the stylesheet.
Writing comments that just repeat what the code already says, instead of explaining the reasoning behind it.

Chapter Summary

CSS comments start with /* and end with */, and everything in between is ignored by the browser.
Comments are useful for explaining tricky decisions, labeling sections, and temporarily disabling rules.
CSS does not support single-line // comments the way some other languages do.

Browser Support

CSS comment syntax has been part of the language from the start and is supported identically by every browser.

🔒

Chapter Quiz — Complete all 7 topics to unlock

0/7 topics done

Complete these topics first:

← Previous Lesson CSS How To Next Lesson → CSS Errors