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

Syntax

css

/* single-line comment */

selector {
  property: value; /* inline comment */
}

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

<style>
/* Fixes a Safari flexbox gap bug -- see issue #482 */
.container {
  gap: 16px;
}
</style>
<div class="container" style="display:flex">
  <div style="background:#cde">One</div>
  <div style="background:#fdc">Two</div>
</div>

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

<style>
/* This is a CSS comment, it can span
   multiple lines */
p {
  color: blue;
}
</style>
<p>Blue text; the comment above is never rendered.</p>

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

<style>
p {
  color: blue;
  /* background: yellow; */
}
</style>
<p>Blue text; the yellow background is commented out.</p>

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

<style>
/*
  Navigation styles
  Used across every page in the site
*/
nav {
  display: flex;
}
</style>
<nav style="background:#eee; padding:8px"><a href="#">Home</a> <a href="#">About</a></nav>

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

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

Live Example

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