Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 139 Β· Getting Started

Comments and Code Organization

Write CSS comments with /* */, use them to disable code while debugging, organize a stylesheet into clear sections, and follow formatting conventions teams rely on.

A stylesheet starts small and grows fast. A few dozen rules become a few hundred, and soon you are scrolling up and down hunting for "that rule that makes the buttons blue". Comments and a sensible structure are what keep a growing stylesheet pleasant to work in, for you six months from now and for anyone else who opens the file.

In this lesson you will learn CSS comment syntax and its quirks, use comments as a debugging tool, and pick up the organizing and formatting habits that professional stylesheets share.

Writing comments

A CSS comment starts with /* and ends with */. Anything in between is ignored by the browser. Comments can sit on their own line, at the end of a line, or span many lines:

CSS
/* Brand colors used across the site */
.logo {
  color: #6b3fa0; /* the official purple */
}

/*
  Cards are used on the home page and in search results.
  Keep padding in sync with .panel below.
*/
.card {
  padding: 1rem;
}

That's the only comment syntax CSS has. There is no single-line // comment like in JavaScript.

// is not a comment in CSS. Inside a declaration block it seems to work, because the browser rejects the line as invalid and skips it up to the next semicolon. But a // line in front of a rule becomes part of that rule's selector, and the whole rule is thrown away. Always use /* */.

Comments and a fake comment

The box gets none of its styles. The browser doesn't see a comment followed by a rule; it sees one rule whose selector is // Box styles: NOT a real comment .box. That selector is invalid, so the entire rule is discarded. Replace the // line with a /* … */ comment and run it again.

Comments don't nest

A comment ends at the very first */, so you can't put one comment inside another:

CSS
/* Outer comment starts
   /* inner comment */
   This text is no longer inside a comment!
*/

After the inner */, the browser is back to reading CSS, and the rest becomes garbage that can break the next rule. When you comment out a block that already contains comments, remove or adjust the inner ones first.

Commenting out code while debugging

Comments are the quickest way to switch a declaration or a whole rule off without deleting it. Most editors toggle a comment on the current line or selection with Ctrl + / (Cmd + / on macOS), and they use the correct /* */ syntax for CSS files.

Switch declarations off

Remove the comment markers around border-radius, then around the second .alert rule, and watch the changes. Commenting out is ideal for quick experiments, but don't leave large blocks of dead code in a finished stylesheet. Version control remembers old code for you; your stylesheet doesn't need to.

What makes a good comment

Code already shows what it does. Good comments explain why, or add context the code can't:

CSS
/* Bad: repeats the code */
.header {
  z-index: 10; /* z-index is 10 */
}

/* Good: explains a decision */
.header {
  z-index: 10; /* above the map widget (z-index: 5), below modals (100) */
}

/* Good: explains a non-obvious value */
.hero {
  min-height: 100svh; /* svh, not vh, so mobile browser bars don't hide the button */
}

/* Good: flags a temporary workaround */
.legacy-table td {
  /* TODO: remove once the old admin pages use the new table component */
  white-space: nowrap;
}

Good candidates for comments are magic numbers, workarounds for browser bugs, dependencies between rules ("keep in sync with…"), and anything a teammate might be tempted to "clean up" without knowing why it exists.

Organizing a stylesheet into sections

Browsers don't care about the order of unrelated rules, but people do. Most well-kept stylesheets follow a general-to-specific order, with a clearly marked section for each kind of rule:

CSS
/* ==========================================================================
   1. Custom properties
   ========================================================================== */

:root {
  --color-text: #1d2433;
  --color-accent: #2563eb;
  --radius: 8px;
}

/* ==========================================================================
   2. Base styles (bare elements)
   ========================================================================== */

body {
  font-family: system-ui, sans-serif;
  color: var(--color-text);
  line-height: 1.5;
}

a {
  color: var(--color-accent);
}

/* ==========================================================================
   3. Layout
   ========================================================================== */

.page {
  max-width: 60rem;
  margin: 0 auto;
}

/* ==========================================================================
   4. Components
   ========================================================================== */

/* Button ------------------------------------------------------------------ */

.button {
  border-radius: var(--radius);
}

/* Card -------------------------------------------------------------------- */

.card {
  border-radius: var(--radius);
}

/* ==========================================================================
   5. Utilities
   ========================================================================== */

.text-center {
  text-align: center;
}

This order isn't arbitrary. Broad rules come first and specific ones later, which works with the cascade: when two rules are equally specific, the later one wins, so a utility like .text-center can override a component without extra effort. Big banner comments make the sections easy to find when scrolling, and a consistent style lets you search for them.

When one file gets too long, split sections into separate files (base.css, layout.css, components/card.css) and combine them with a build step. Modern CSS also offers cascade layers, which let you make this order official, and Organizing CSS explores naming conventions like BEM.

A small organized stylesheet

Try changing --accent in the custom properties section. The heading and the badge both update, because they share the value. Grouping shared values at the top like this is one of the best organizing habits you can build. Custom Properties covers it in depth.

Formatting conventions

Teams argue about many style details, but these conventions are nearly universal, and following them makes your CSS look familiar to everyone:

  • One selector per line in a group, and one declaration per line.
  • Indent declarations by two spaces (or whatever your project uses, consistently).
  • A space after the colon, none before: color: red;.
  • A space before the opening brace, and the closing brace on its own line.
  • A blank line between rules.
  • Always end declarations with a semicolon, including the last one.
  • Lowercase for properties, values, element names, and hex colors (or uppercase hex, but pick one).
  • Meaningful class names that describe purpose (.error-message) rather than appearance (.red-text), so they still make sense after a redesign.

You don't have to enforce this by hand. A formatter such as Prettier can format CSS automatically every time you save, and a linter such as Stylelint can catch errors like unknown properties or duplicate selectors. Both are worth setting up on any real project.

Check your understanding

Quick check Β· 5 questions

of 5 answered You scored / 5 Β· perfect!

  1. 1. Which is a valid CSS comment?

    CSS has only one comment syntax, /* … */. The others belong to JavaScript, HTML and other languages.
  2. 2. You write // Header on the line above a .header { … } rule. What happens?

    The browser doesn't recognize // as a comment. It reads // Header .header as the selector, which is invalid, so the whole rule is discarded.
  3. 3. You comment out a block that already contains a comment. What goes wrong?

    A comment always ends at the first */. Text after it is parsed as CSS and can break nearby rules.
  4. 4. Which comment is most useful?

    Good comments explain why. The last one explains a magic number that a reader couldn't work out from the code alone.
  5. 5. Why do many stylesheets put utilities like .text-center at the end?

    Ordering from general to specific works with the cascade, because source order breaks ties between equally specific selectors.

Summary

  • CSS comments use /* … */ only; // is not a comment and can silently discard the rule after it.
  • Comments don't nest: the first */ always ends the comment.
  • Commenting out is a fast debugging tool; delete dead code once you're done.
  • Good comments explain why: decisions, magic numbers, workarounds and dependencies.
  • Organize stylesheets from general to specific: custom properties, base, layout, components, utilities.
  • Keep formatting consistent and let tools like Prettier and Stylelint enforce it.

Next: Inspecting CSS with DevTools, where you learn to see exactly which rules apply to any element and edit them live.