CSS — Comments

Writing notes in CSS

CSS has exactly one comment syntax — /* ... */:

/* Brand color — change here only */
:root {
    --brand: #0d9488;
}

.card {
    /* padding must stay under 16px per design system */
    padding: 16px;
}

There is no // or # comment in CSS (those belong to JS and Sass):

// wrong — this breaks the next rule
p { color: red; }

The browser hits //, can't parse it, and silently drops the rule that follows. Classic invisible bug.

What comments are for

1. Section markers in long stylesheets

/* ============ LAYOUT ============ */
.container { max-width: 1100px; margin: 0 auto; }

/* ============ BUTTONS ============ */
.btn { padding: 10px 20px; border-radius: 6px; }

/* ============ FORMS ============ */
input { padding: 8px; }

2. Explaining why, not what

/* z-index needs to sit above the sticky header (z-index: 100) */
.modal { z-index: 200; }

/* Safari ignores inset shorthand before 14.1 — split properties */
.banner { top: 0; left: 0; right: 0; bottom: 0; }

3. Disabling rules while debugging

.hero {
    background: url("mountain.jpg");
    /* position: fixed;   ← suspect! testing without it */
    height: 100vh;
}

Comment out a suspicious declaration → refresh → check → restore or delete. The CSS version of scientific method.

Multi-line and placement

Comments can wrap several lines and live almost anywhere — between rules, inside rules around declarations, even between selectors:

/*
.card {
    experimental grid layout — revisit after QA
}
*/

h1 /* page title */ {
    color: teal;
}

But like HTML comments, they don't nest — the first */ closes everything:

/* outer
   /* inner */
still-active CSS! */   ← this becomes a parse error zone

Comments are public

Stylesheets ship to every visitor — View Source reveals everything:

/* WRONG: admin panel is at /secret-admin, password hint below */

Never put credentials, internal URLs or client names you shouldn't expose.

Mini Practice

1. Organize an existing stylesheet with three ===== section banners
2. Add a why comment documenting a non-obvious value choice
3. Comment out a property, verify the visual change, restore it
4. Try // once on purpose — meet the silent breakage firsthand

Next: outline →