On this page

CSS Comments & Code Formatting Best Practices

Badar KhalilUpdated September 29, 2026 3 min read

CSS Comments: Syntax and Purpose

CSS comments are notes in your stylesheet that the browser ignores. They explain your code, organize sections and let you temporarily disable rules. Clean commenting and consistent formatting make your CSS readable, debuggable and team-friendly.

CSS Comment Syntax

CSS has only one comment style: it starts with a slash and an asterisk, and ends with an asterisk and a slash. Comments can span one or many lines.

Important: CSS does not support the double-slash (//) comment used in JavaScript. Using // in plain CSS will break the rule that follows it. (Preprocessors such as Sass and SCSS do allow // comments, but they are compiled away.)

When to Use Comments

Section headers - divide the file into logical parts (Base, Layout, Components, Utilities).
Explaining why - describe the reason for a hack, browser fix or magic number, not what the code obviously does.
Debugging - comment out declarations to test the effect.
TODO and FIXME notes - mark work that needs attention.
Documentation - describe variables, components and states for teammates.

When NOT to Comment

Do not restate the obvious, such as a comment 'sets color to red' above color: red.
Do not leave large blocks of dead, commented-out code in production.
Do not put sensitive information in comments: CSS files are public.

Nested Comments Do Not Work

A comment ends at the first closing marker it finds. So you cannot nest one comment inside another; remove or rearrange inner comments before commenting out a large block.

CSS Code Formatting Best Practices

One selector and one declaration per line for readability and clean version-control diffs.
Consistent indentation - 2 spaces is the most common convention (or 4). Pick one.
Space after the colon and before the opening brace.
Always end declarations with a semicolon.
Lowercase for selectors, properties and hex colors, and kebab-case for class names (main-nav, not MainNav).
Use meaningful class names that describe purpose, not appearance (.alert-error rather than .red-box).
Group related properties (layout, box model, typography, visual, misc) in a consistent order.
Leave a blank line between rules.
Use shorthand where clear, for example margin: 10px 20px.

Naming Conventions: BEM

BEM (Block, Element, Modifier) is a popular naming method: .card (block), .card__title (element), .card--featured (modifier). It keeps specificity low and avoids naming collisions.

Organizing a Stylesheet

Variables and custom properties (:root)
Reset or base styles
Layout (containers, grid, header, footer)
Components (buttons, cards, forms)
Utilities (helpers such as .visually-hidden)
Media queries and dark-mode overrides

Automatic Formatting and Linting Tools

Prettier - formats CSS automatically on save.
Stylelint - detects errors, duplicate properties and enforces your style rules.
EditorConfig - keeps indentation consistent across editors.
Minification - production builds remove comments and whitespace to reduce file size, so write freely in development.

Key Takeaways

CSS comments use the slash-asterisk syntax only.
Comment the why, not the what.
Format consistently: indentation, one declaration per line, kebab-case names.
Use Prettier and Stylelint to automate quality.

Try it Yourself CSS

/* This is a single-line CSS comment */

/*
  This is a multi-line comment.
  Use it for longer explanations.
*/

h1 {
  color: navy; /* inline comment after a declaration */
}

Output

Press Run to execute.

Try it Yourself HTML

<style>
  p {
    color: green;
    /* font-size: 40px; */
    /* Uncomment the line above to see the effect */
  }
</style>
<p>Comment out the font-size line to disable it, then remove the comment markers to enable it.</p>

Output

Press Run to execute.

Try it Yourself CSS

/* ==========================================
   1. VARIABLES
   ========================================== */
:root {
  --primary: #0d6efd;
  --text: #222;
  --space: 16px;
}

/* ==========================================
   2. BASE
   ========================================== */
body {
  color: var(--text);
  margin: 0;
}

/* ==========================================
   3. COMPONENTS
   ========================================== */
.btn {
  padding: var(--space);
  background: var(--primary);
  color: white;
}

Output

Press Run to execute.

Try it Yourself CSS

/* BAD: hard to read */
.Card{color:red;background:#FFF;margin:0 auto;padding:10px}

/* GOOD: clean and consistent */
.card {
  margin: 0 auto;
  padding: 10px;
  color: red;
  background: #fff;
}

Output

Press Run to execute.

Try it Yourself HTML

<style>
  .card { border: 1px solid #ccc; padding: 16px; max-width: 280px; font-family: sans-serif; }
  .card__title { margin: 0 0 8px; font-size: 20px; }
  .card__text { margin: 0; color: #555; }
  .card--featured { border-color: gold; background: #fffbe6; }
</style>
<div class='card card--featured'>
  <h3 class='card__title'>BEM Card</h3>
  <p class='card__text'>Block, Element, Modifier naming keeps CSS predictable.</p>
</div>

Output

Press Run to execute.

Exercise: Clean Up Messy CSSCSS

Rewrite the messy CSS with one declaration per line, 2-space indentation, lowercase values, and add a comment above the rule that explains what it styles.

Try it Yourself CSS

/* Reformat this code */
.Main-Nav{DISPLAY:flex;GAP:20PX;background:#FFF;padding:10px 20px}

Output

Press Run to execute.

Show expected output

.main-nav rule formatted across multiple lines with a descriptive comment.

This is a self-check — compare your result with the expected output above.

Was this page helpful?