CSS Comments & Organization
CSS has one comment syntax and no way to nest it, which is easy to underestimate — comments end up doing a lot of quiet, important work in a stylesheet: explaining why a rule exists, not just what it does, and giving a long file enough structure to navigate without reading every line.
Comment syntax
/* This is a CSS comment */
.button {
color: blue; /* inline comments work too */
}
/*
Multi-line comments are just the same syntax,
spanning as many lines as needed.
*/
/* Comments CANNOT be nested: */
/* this /* breaks */ the comment early */*/ they encounter, so you cannot "comment out" a block of CSS that already contains a comment inside it without first removing the inner comment — the outer one will terminate early and leave stray CSS uncommented.Documenting magic numbers and hacks
The single highest-value use of a CSS comment is explaining a value that looks arbitrary. Six months from now, nobody — including you — will remember why that number is there.
.dropdown {
/* 52px = header height (48px) + 4px border, keeps the dropdown flush
against the header regardless of future header padding changes */
top: 52px;
}
.tooltip {
/* Safari-only: WebKit renders this filter with a 1px offset unless
translateZ(0) forces its own compositor layer. Remove if Safari
ever fixes this (last checked: Safari 17). */
transform: translateZ(0);
}Section headers for navigation
In a long, single stylesheet, banner-style comments act like a table of contents — most editors let you jump between them, and they make the file skimmable without a build step.
/* ==========================================================================
Layout
========================================================================== */
.page { }
.sidebar { }
/* ==========================================================================
Components
========================================================================== */
.card { }
.button { }
/* --------------------------------------------------------------------------
Buttons: variants
-------------------------------------------------------------------------- */
.button--primary { }
.button--secondary { }TODO conventions
A consistent TODO/FIXME prefix makes stray work-in-progress comments searchable across an entire codebase.
/* TODO(firoz): replace with a design-token color once the palette
refresh ships */
.badge {
background: #ffefc2;
}
/* FIXME: this workaround breaks in RTL layouts, needs a logical-property
rewrite */
.icon {
margin-left: 8px;
}Convention | Meaning |
|---|---|
| Planned follow-up work, not urgent |
| Known bug or incorrect behavior that needs fixing |
| Intentional workaround, explain why it exists and its removal condition |
| Context worth knowing, not necessarily actionable |
TODO with no owner and no date tends to live forever. TODO(name) or a linked ticket number makes it traceable back to someone who can answer questions about it later.Comments and minification
Build tools strip comments from the shipped CSS by default, so verbose comments cost nothing in production bundle size. There is rarely a reason to under-comment source CSS out of concern for file size — the minifier handles that automatically.
/* Source (readable, well-commented) */
.card {
/* Matches the design system's default corner radius */
border-radius: 8px;
}
/* Minified output (comments removed, whitespace collapsed) */
/* .card{border-radius:8px} */When comments become lies
Prefer comments that explain why, not what — the CSS itself already says what it does
Keep a comment and the code it describes in the same diff, so they cannot drift apart silently
Delete workaround comments once the underlying bug or browser quirk is actually fixed
Use consistent section-header banners in large files so the structure is scannable
Do not worry about comment verbosity for bundle size — minifiers strip them entirely
Comments in Sass/Less (//)
Preprocessors add a second comment syntax, // for single-line comments, which is stripped entirely at compile time and never appears in the compiled CSS output — even before minification. Plain /* */ comments, by contrast, are preserved in the compiled CSS (though a minifier can still strip them afterward).
// This line never reaches the compiled CSS at all (Sass/Less only)
$primary-color: #2563eb;
/* This comment IS compiled into the output CSS, and only removed if
the build additionally runs a minifier */
.button {
color: $primary-color;
}Linting comment conventions with Stylelint
Stylelint can enforce comment formatting rules across a team — for example, requiring a space after the opening /*, or banning empty comments left over from editing.
/* stylelint-disable-next-line declaration-no-important */
.utility-override {
color: red !important;
}stylelint-disable comment doubles as an explicit, visible admission that a rule is being deliberately broken — which is exactly the kind of thing worth a follow-up comment explaining why, so a future reader does not assume it was accidental.Comment-driven style guides
Some documentation tools (like KSS — Knyle Style Sheets) parse specially formatted CSS comments to auto-generate a living style guide directly from the stylesheet, keeping the documentation physically next to the code it describes.
/*
Button
Primary call-to-action button used across the marketing site.
Markup: <button class="button">Click me</button>
Style guide: components.button
*/
.button {
padding: 8px 16px;
border-radius: 6px;
}The ASCII-art banner critique
==== underline shown earlier) gets the same navigation benefit with far less maintenance overhead.