CSS Comments

Learn how to properly use comments in CSS to document your code and make it more maintainable

What are CSS Comments?

Comments are used in CSS to explain code, make notes, or temporarily disable parts of the code. Comments are ignored by browsers and are not displayed on the rendered page.

Why use comments?

  • Explain the purpose of specific CSS rules
  • Organize your stylesheet into sections
  • Temporarily disable code without deleting it
  • Leave notes for yourself or other developers
  • Mark sections for future improvements

Single-Line Comments

Syntax

Single-line comments start with /* and end with */.

/* This is a single-line comment */

body {
  font-family: Arial, sans-serif;  /* Set default font */
  margin: 0;                     /* Remove default margin */
  padding: 0;                    /* Remove default padding */
}

Best Practices

  • Use single-line comments for short explanations
  • Place comments above the code they reference or on the same line
  • Keep comments concise and to the point
  • Use consistent formatting for all comments

Note: Unlike some programming languages, CSS doesn't support comments that start with //. You must use /* */ for all comments.

Multi-Line Comments

Syntax

Multi-line comments use the same syntax as single-line comments but can span multiple lines.

/*
This is a multi-line comment
It can span across several lines
*/

/*
 * Header Styles
 * This section contains all styles
 * related to the header component
 */
header {
  background: #333;
  color: white;
  padding: 1rem 0;
}

Best Practices

  • Use multi-line comments for longer explanations or section headers
  • Consider using a consistent pattern like asterisks on each line
  • Use multi-line comments to temporarily disable large blocks of code
  • Keep comments updated when the related code changes

Section Headers Example:

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

Practical Examples

Well-Commented CSS Example

/* Style the header */
header {
  background-color: #333;
  color: white;
  padding: 1rem;
}

/* Main content area */
.main-content {
  max-width: 1200px;
  margin: 0 auto;
  padding: 2rem;
}

/* Footer styling */
footer {
  text-align: center;
  margin-top: 2rem;
  padding: 1rem;
  border-top: 1px solid #ccc;
}

Commenting for Organization

Use comments to create a table of contents for larger stylesheets:

/* ============================================
TABLE OF CONTENTS
============================================
1. Reset Styles
2. Typography
3. Layout
4. Header
5. Navigation
6. Main Content
7. Sidebar
8. Footer
9. Media Queries
============================================ */

Commenting Best Practices

Do's

  • Comment why you're doing something, not what you're doing
  • Use comments to separate sections of your stylesheet
  • Keep comments relevant and up-to-date
  • Use consistent formatting for all comments
  • Comment complex or non-obvious code solutions
  • Use comments to mark TODOs and FIXMEs

Don'ts

  • Don't state the obvious - the code should speak for itself
  • Avoid outdated comments that no longer reflect the code
  • Don't use excessive commenting that makes code hard to read
  • Avoid emotional or non-professional comments
  • Don't comment out large blocks of code in production
  • Avoid nested comments (comments within comments)

Commenting for Maintenance

Comments can be extremely helpful for future maintenance. Here are some patterns to consider:

TODO Comments

/* TODO: Refactor this when browser support improves */

FIXME Comments

/* FIXME: This causes layout issues in Safari */

Section Headers

/* ========== Form Styles ========== */

Browser Hacks

/* IE9-specific fix */
< NextNext >