CSS Comments

Let’s be honest for a second: nobody opens a stylesheet excited to read it. But there’s a huge difference between a CSS file that makes you go “what is even happening here” and one that actually guides you through the logic, tells you why something was done, and saves you 30 minutes of guessing.

That difference? Comments.

We already covered HTML comments in detail earlier in this series, and if you’ve been following along, you know how much a single well-placed comment can save your brain. CSS comments work on the same principle, but the stakes are higher, because stylesheets tend to grow fast and get messy in ways HTML rarely does.

This lesson is all about that: writing CSS comments that actually help, not just noise that clutters the file.

01How CSS Comments Actually Work

CSS only has one style of comment. Unlike some languages that give you both single-line and multi-line options, CSS keeps it simple with one syntax:

/* This is a CSS comment */

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

That’s it. Everything between /* and */ is completely ignored by the browser. It doesn’t render, doesn’t affect layout, doesn’t slow anything down in production (once you minify, they’re gone anyway).

One thing to keep in mind: CSS does not support // single-line comments the way JavaScript does. If you write // color: red; in a CSS file, it won’t be treated as a comment, it’ll just be invalid and ignored. Stick to /* ... */.

/* ✅ This works perfectly */
color: blue;

// ❌ This does NOT work in CSS — not a valid comment
color: red;

02Why Most Developers Skip CSS Comments (And Regret It)

Here’s something I’ve seen happen a lot: a developer writes a stylesheet, ships it, and feels great. Six months later, a teammate opens that file and there’s just… no context. Numbers everywhere. Values that make no sense. A margin-top: -3px that looks like a bug but is actually a very intentional fix for a very specific rendering issue in a very specific browser.

Without a comment, that fix disappears. Someone deletes it, thinking it’s an error, and suddenly something is broken in Firefox again.

This happens all the time. And it’s so easy to prevent.

Good CSS commenting habits are also a skill that separates junior developers from people who’ve been burned enough times to know better. If you’re building anything that someone else will touch, or that you’ll touch again in three months, comments are not optional.

03Writing Meaningful CSS Comments: What Actually Helps

There’s a difference between a comment that tells you what the code does (which you can already read from the code) and a comment that tells you why it does it.

The “why” is almost always the useful one.

Don’t describe the obvious

/* Sets color to red */
color: red;

This adds zero value. Anyone reading CSS knows what color: red does.

Explain the reason behind a decision

/* Using red here to match the brand error state defined in the design system */
color: red;

Now that’s useful. Now you know this wasn’t random, it connects to something.

Document non-obvious values

/* 
  z-index: 999 keeps the dropdown above the sticky header (z-index: 100)
  and above the modal overlay (z-index: 500)
*/
.dropdown-menu {
  z-index: 999;
}

This is gold. Without this comment, every developer who opens this file will spend time mentally tracing the z-index stack. You just saved them that work.

04CSS Section Separators: Organizing Stylesheets Like a Pro

Long stylesheets, and they will get long, need visual breaks. Section separators are comments that act like chapter headings in your CSS file. They make it immediately obvious where one section ends and another begins.

Here’s a clean pattern that works well:

/* ==========================================================================
   RESET & BASE STYLES
   ========================================================================== */

*, *::before, *::after {
  box-sizing: border-box;
}


/* ==========================================================================
   TYPOGRAPHY
   ========================================================================== */

body {
  font-family: 'Inter', sans-serif;
  font-size: 16px;
  line-height: 1.6;
}


/* ==========================================================================
   NAVIGATION
   ========================================================================== */

nav {
  display: flex;
  align-items: center;
}


/* ==========================================================================
   BUTTONS
   ========================================================================== */

.btn {
  display: inline-flex;
  padding: 0.6em 1.2em;
  border-radius: 6px;
}

This is a pattern used in popular CSS frameworks and well-maintained design systems. It costs you about five seconds to write and saves everyone scanning the file a lot of scrolling.

Some teams prefer a shorter version:

/* ---- Navigation ---- */

/* ---- Buttons ---- */

/* ---- Footer ---- */

Either works. The important thing is that you pick one style and stay consistent across your file and team.

05Documenting Browser-Specific CSS Fixes

This is one of the most valuable uses of CSS comments, and also one of the most skipped.

Browser bugs are real. Sometimes you need a weird value, a specific hack, or a property only one browser understands, just to make something render correctly. If you don’t document these, someone will delete them assuming they’re mistakes.

.flex-container {
  display: flex;
  align-items: center;

  /* Fix: Safari 14 ignores gap on flex containers — use margin as fallback */
  gap: 16px;
}

.image-wrapper {
  /* Fix: IE 11 doesn't support object-fit — this is handled via JS polyfill */
  object-fit: cover;
}

.smooth-scroll-section {
  /* 
    -webkit-overflow-scrolling: touch is deprecated in modern iOS 
    but kept here for iOS 12 and below support per project requirements
    Remove this once analytics shows < 1% iOS 12 traffic
  */
  -webkit-overflow-scrolling: touch;
  overflow-y: scroll;
}

Notice something about that last comment: it tells you when it's safe to remove the fix. That's the kind of forward-thinking documentation that saves teams a lot of time during future cleanup.

A good browser fix comment should include:

• What browser or version has the bug
• What the bug actually does
• Why this specific fix solves it
• When it can be removed (if known)

06TODO and FIXME Notes in CSS: How to Use Them Right

TODO notes are everywhere in code, and CSS is no exception. They're a quick way to flag things that need attention without stopping your flow while writing styles.

/* TODO: Replace this hardcoded color with the CSS variable --color-primary */
.hero-title {
  color: #6366f1;
}

/* TODO: This section needs dark mode support — revisit after design review */
.notification-bar {
  background: #fff;
  color: #1a202c;
}

/* FIXME: The hover state on mobile triggers on first tap, not second — 
   needs pointer media query or JS touch detection */
.card:hover {
  transform: translateY(-4px);
}

/* HACK: Using overflow:hidden to clear the float — 
   should be refactored to flexbox when time allows */
.legacy-float-container {
  overflow: hidden;
}

A few conventions that teams often agree on:

• TODO: Something that needs to be done, not urgent
• FIXME: Something that's broken or broken-ish, needs attention
• HACK: This works but it's not clean, flag it for refactoring
• NOTE: Important context that isn't a task, just information

These tags also work great with code editors. Most editors like VS Code can highlight or even list all TODO/FIXME comments in a file if you install the right extension, making it easy to track what needs cleanup.

07Commenting Out CSS Code During Debugging

This one is more about the day-to-day workflow. Sometimes you want to temporarily disable a chunk of CSS to see what's causing an issue, without deleting it entirely.

.hero {
  background: linear-gradient(135deg, #6366f1, #ec4899);
  
  /* Temporarily disabled to debug layout shift: */
  /* padding: 80px 40px; */
  
  color: white;
}

This is completely valid and very common during development. The key is: clean them up before you commit. Leaving commented-out code in production stylesheets turns into clutter very quickly.

A good rule: if you commented something out and it's been sitting there for more than a week, either bring it back or delete it.

08CSS File Header Comments: The Metadata Approach

For professional or team projects, it's common to put a header comment at the very top of a CSS file, especially if the project has multiple stylesheets. It sets the context immediately.

/* ==========================================================================
   components/buttons.css
   
   All button styles: primary, secondary, ghost, icon-only, and disabled states.
   Design tokens used: --color-primary, --color-secondary, --radius-md
   
   Last reviewed: 2024-08
   Author: Daniyal
   ========================================================================== */

This is especially helpful in larger projects where you have many component CSS files. Opening a file and immediately knowing what it's for and what it depends on saves you the time of reading through everything to understand the scope.

Not every project needs this level of detail, but for anything shared across a team or maintained over months, it's worth it.

09A Real-World Example: A Well-Commented Stylesheet Section

Let's put this all together. Here's what a card component's CSS might look like when properly commented:

/* ==========================================================================
   CARD COMPONENT
   Used on: /blog, /products, /dashboard
   ========================================================================== */

.card {
  background: var(--color-surface);
  border-radius: 12px;
  
  /* Shadow value matches elevation-2 from the design system */
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.12);
  
  overflow: hidden;
  
  /* 
    position: relative here is intentional — it creates a stacking context
    so the .card__badge (position: absolute) stays contained inside the card
    and doesn't escape to the document root
  */
  position: relative;
}

.card__image {
  width: 100%;
  aspect-ratio: 16 / 9;

  /* Fix: Safari 15 and below doesn't honor aspect-ratio on images —
     using a wrapper div with padding-top hack as fallback is tracked in issue #482 */
  object-fit: cover;
}

.card__body {
  padding: 24px;
}

.card__title {
  font-size: 1.125rem;
  font-weight: 600;
  
  /* Limit to 2 lines on listing pages — see design spec v3.2 */
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

.card__badge {
  position: absolute;
  top: 12px;
  right: 12px;
  
  /* TODO: Replace hardcoded color with semantic token when design system v2 ships */
  background: #6366f1;
  color: white;
  font-size: 0.75rem;
  padding: 4px 10px;
  border-radius: 999px;
}

Look at how much clarity that file has. Even if you'd never seen this codebase before, you'd understand what every section is doing and why specific decisions were made.

10Documenting Your Z-Index Scale (A Practical Tip)

Since we're on the topic: z-index is one of the most confusing parts of CSS to manage in a team. Everyone's setting their own random numbers and nothing makes sense after a while.

A documented z-index scale at the top of your stylesheet (or in a dedicated variables file) solves this immediately:

/* ==========================================================================
   Z-INDEX SCALE
   Use only these values to keep stacking contexts predictable
   
   1      - Page content
   10     - Sticky table headers, floating labels
   100    - Sticky navigation
   200    - Drawers / side panels
   500    - Modals and overlays
   999    - Tooltips, dropdowns
   9999   - Emergency: dev tools, cookie banners
   ========================================================================== */

:root {
  --z-sticky: 100;
  --z-drawer: 200;
  --z-modal: 500;
  --z-tooltip: 999;
}

Notice how the comment and the CSS variables work together here. The comment explains the whole system, the variables make it easy to apply. This kind of thinking is what separates stylesheets that are pleasant to work with from ones that are a nightmare to debug.

We actually looked at CSS variables briefly in the Introduction to CSS lesson, and you'll see them more and more as you go deeper into writing maintainable stylesheets.

11Inline Comments vs Block Comments: When to Use Which

There's no hard rule here, but a general pattern that works well:

Block comments for sections, context, and multi-line explanations

/* 
  The hero section uses a full-viewport height layout.
  We subtract the nav height (64px) to prevent content going under it.
  This var is set in :root and should match the actual nav height.
*/
.hero {
  min-height: calc(100vh - var(--nav-height));
}

Inline comments for quick, single-property clarifications

.hero {
  min-height: calc(100vh - var(--nav-height)); /* 100vh minus sticky nav */
  padding: 0 clamp(1rem, 5vw, 4rem); /* responsive horizontal padding */
}

Both are valid. Inline comments are great for quick notes. Block comments are better when you need to explain something in more detail or mark a section boundary.

12CSS Comments and Performance: Does It Matter?

Yes and no. In development, comments have zero impact on how your page renders. The browser simply ignores them.

In production, if you're using a CSS minifier (which you should be for any serious project), comments are stripped out automatically. So your end users never download a single byte of your comments.

The only exception: some minifiers recognize special comment syntax like /*! ... */ (with an exclamation mark) as important and preserve them even after minification. This is useful for license headers:

/*!
 * Project Name v1.0.0
 * Copyright 2024 Your Name
 * MIT License
 */

This pattern is common in open source CSS libraries. But for most projects, you won't need it.

13Building a CSS Commenting Style Guide for Your Team

If you work with others, or even just want to stay consistent with yourself, having a short commenting style guide is worth making. It doesn't have to be formal, just a few agreed-upon conventions:

The goal isn't to have a rigid system. It's to have a shared language so that when someone sees a certain pattern, they immediately know what it means and what to do with it.

14Quick Reference: CSS Commenting Patterns at a Glance

/* Basic comment */
color: blue;

/* =======================================================================
   SECTION SEPARATOR
   ======================================================================= */

/* Multi-line block comment
   for longer explanations */

/* TODO: action needed in the future */

/* FIXME: something broken or unreliable */

/* HACK: works but not the right solution */

/* NOTE: important context, not a task */

/* Fix: Safari 14 — gap on flex doesn't work */

/*! Preserved comment — survives CSS minification */

15What Comes Next in This Series

Now that you know how to write CSS that's not just functional but also readable and maintainable, the next lesson digs into something that trips up almost every beginner (and honestly, a lot of experienced developers too): the CSS Cascade.

You've probably run into moments where you write a style and it just doesn't apply, no matter what you do. That's the cascade at work. Understanding how browsers process CSS and how the cascade decides which styles win is honestly one of the most important things to understand in CSS, and the next lesson covers exactly that.

If you've ever wondered why your color declaration isn't working, or why adding !important feels like a guess, that lesson is going to make a lot of things click.

For now, start adding comments to your stylesheets. Even small ones. Even just section separators. It's a habit that takes almost no time to build and pays back ten times over the longer you write CSS.