What You’ll Learn

CSS comments let you add notes to stylesheets that browsers ignore. Use them to document code, organize sections, and temporarily disable rules during debugging.

Introduction

CSS comments are notes written inside a stylesheet for developers. They help you and your team understand why styles exist, mark sections of a large file, and leave reminders for future edits.

Definition and Usage

A comment is any text wrapped in /* and */. The browser completely ignores comment content — it does not affect layout, colors, fonts, or any visual output.

Comments are also useful for temporarily disabling CSS rules. Instead of deleting a rule while debugging, wrap it in a comment and restore it later.

📝 Syntax

Wrap comment text between /* and */:

/* This is a single-line comment */

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

Place comments anywhere in a CSS file — between rules, inside rule blocks, or at the end of a line:

/* Header styles */
header {
  background: #2563eb; /* brand blue */
  color: #fff;
}

Comment Types

Important Rules

• Comments cannot be nested — the first */ closes the comment.
• Comments do not appear on the rendered page but are visible in source and DevTools.
• In external CSS, @charset must be the first line — no comments before it.
• Never store passwords, API keys, or private data in comments.

When to Use Comments

Reach for CSS comments in these situations:

• Section headers — Label groups like Header, Navigation, Footer in large files.
• Explaining why — Document non-obvious values, hacks, or browser fixes.
• Debugging — Temporarily disable rules to isolate layout problems.
• Team handoff — Leave notes for other developers maintaining the stylesheet.
• TODO reminders — Mark styles that need cleanup or refactoring later.

Skip comments that merely repeat what the code already says, like /* sets color to red */ above color: red;.

Examples Gallery

Practice CSS comments with basic syntax, commenting out rules, multi-line documentation, and inline notes.

/* This comment is for developers only */

body {
  font-family: system-ui, sans-serif;
  padding: 1.5rem;
  color: #1e293b;
}

/*
.highlight {
  background: #fef3c7;
  padding: 0.5rem;
}
*/

p {
  margin: 0;
  font-family: system-ui, sans-serif;
}

/*
  Navigation styles
  - Flex layout for horizontal links
  - Updated: July 2026
*/
nav {
  display: flex;
  gap: 1rem;
  padding: 0.75rem 1rem;
  background: #1e293b;
}

.card {
  padding: 1rem 1.25rem;
  background: #eff6ff;
  border-radius: 0.5rem;
  box-shadow: 0 4px 6px rgba(0,0,0,0.08); /* subtle depth */
}

💬 Usage Tips

• Explain why, not what — Good: /* fix Safari flex gap */. Bad: /* set display to flex */.
• Section headers — Use banner comments to divide large stylesheets into clear regions.
• Keep comments current — Update or remove notes when the code changes.
• Short inline notes — One line after a tricky property is enough.
• Use version control — Git tracks history; you do not need to keep old code in comments.

⚠️ Common Pitfalls

• Using // syntax — // is not valid CSS and can break your stylesheet.
• Nested comments — /* outer /* inner */ */ does not work; the first */ closes the comment.
• Comments before @charset — Can invalidate @charset in external CSS files.
• Outdated comments — Misleading notes are worse than no comments at all.
• Secrets in comments — Comments are visible in source code and DevTools.

♿ Accessibility

• Comments are invisible — Never put essential information only in comments; users cannot read them.
• Screen readers ignore comments — Accessibility text must be in HTML content, not CSS notes.
• Do not hide content via comments — Use proper CSS or HTML patterns instead of commenting out accessible markup.
• Document a11y fixes — Comments can explain focus styles or contrast overrides for maintainers.
• Keep file size reasonable — Very large comment blocks slightly increase CSS file size.

💡 Best Practices