What Are CSS Comments?

CSS comments are notes you add to your stylesheets that browsers completely ignore. They are meant for developers to explain what the code does, why certain decisions were made, and to organize large stylesheets into logical sections.

CSS Comment Syntax

In CSS, comments are written between /* and */, and anything inside these symbols is skipped by the browser.

CSS

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

/*
  This is a multi-line CSS comment.
  It can span across multiple lines.
  Very useful for longer explanations.
*/

Unlike HTML and JavaScript, CSS only has one type of comment syntax. There is no single-line comment using // in CSS.

Why Use CSS Comments?

Comments serve several important purposes in your stylesheets:

Documentation: Explain complex selectors or property values
Section Headers: Divide your stylesheet into organized sections
Debugging: Temporarily disable CSS rules during testing
Team Communication: Help other developers understand your code

Organizing Stylesheets with Section Comments

A well-organized stylesheet uses comments to create clear sections:

CSS

/* ================================
   RESET & BASE STYLES
   ================================ */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

/* ================================
   TYPOGRAPHY
   ================================ */
body {
  font-family: Arial, sans-serif;
  line-height: 1.6;
}

h1, h2, h3 {
  margin-bottom: 1rem;
}

/* ================================
   LAYOUT
   ================================ */
.container {
  max-width: 1200px;
  margin: 0 auto;
  padding: 0 1rem;
}

/* ================================
   HEADER
   ================================ */
.header {
  background-color: #333;
  color: white;
  padding: 1rem 0;
}

Commenting Out Code for Debugging

One of the most practical uses of comments is temporarily disabling CSS rules to debug layout issues:

CSS

.card {
  background: white;
  /* border: 2px solid red; */
  padding: 1rem;
  /* margin-bottom: 2rem; */
  border-radius: 8px;
}

This lets you test how removing certain properties affects the layout without deleting the code.

Best Practices for CSS Comments

Do Comment

Complex calculations or unusual property values
Browser-specific hacks or workarounds
Dependencies between different CSS rules
TODO items for future improvements

Avoid Over-Commenting

CSS

/* BAD: Obvious comments add clutter */
/* Set color to red */
color: red;

/* GOOD: Explain WHY, not WHAT */
/* Brand primary color - matches logo */
color: #e74c3c;

File-Level Organization Tips

For larger projects, consider these organization strategies:

Table of Contents: Add a comment at the top listing all sections
Consistent Section Headers: Use the same format for all section dividers
Logical Grouping: Group related styles together (layout, typography, colors)
Component-Based Structure: Organize by UI component rather than property type

CSS

/*
  TABLE OF CONTENTS
  1. Reset & Base
  2. Typography
  3. Layout
  4. Header
  5. Navigation
  6. Main Content
  7. Sidebar
  8. Footer
  9. Utilities
*/

Summary

CSS comments are an essential tool for writing maintainable stylesheets. Use them to document decisions, organize sections, and debug issues. Well-commented CSS makes your code easier to understand, maintain, and collaborate on with other developers.