CSS Comments: Complete Guide with Examples and Best Practices
CSS comments are one of the most underrated yet powerful features in web development. They do not affect how a website looks, but they greatly affect how developers understand, maintain, and debug CSS code.
Whether you are a beginner learning CSS or an experienced developer working on large projects, understanding CSS comments properly will make your code cleaner, clearer, and more professional.
What Are CSS Comments?
CSS comments are notes written inside a CSS file that are ignored by the browser. They exist only for humans, not for machines.
They help developers:
- Explain what a section of CSS does
- Temporarily disable CSS rules
- Organize large stylesheets
- Collaborate better with teams
- Debug styling issues
Browsers completely ignore comments when rendering a webpage.
Syntax of CSS Comments
CSS supports only one type of comment syntax.
Basic Syntax
/* This is a CSS comment */
Anything written between /* and */ is treated as a comment.
Single-Line CSS Comments
CSS does not have a special single-line comment syntax like //.
However, you can still write short comments on one line.
Example
/* Main container styles */
.container {
width: 100%;
}
Even though it’s called a “single-line” comment, it still uses /* */.
Multi-Line CSS Comments
CSS comments can span multiple lines, making them ideal for explanations and documentation.
Example
/*
This section styles the main header
Author: Dibya Lochan Mendali
Last updated: 2026
*/
header {
background-color: #222;
color: white;
}
Why CSS Comments Are Important
1. Improves Code Readability
Well-commented CSS helps anyone understand:
- Why a style exists
- What problem it solves
- Where changes should be made
2. Helps in Debugging
You can temporarily disable CSS rules using comments.
/*
.button {
background-color: red;
}
*/
This is useful when testing layout or fixing bugs.
3. Essential for Team Projects
In collaborative environments, comments:
- Prevent confusion
- Reduce mistakes
- Speed up development
4. Makes Maintenance Easier
Months later, comments help you remember:
- Design decisions
- Browser-specific fixes
- Performance tweaks
Where CSS Comments Can Be Used
CSS comments can be placed almost anywhere.
Inside Selectors
.button {
color: white; /* Text color */
background: blue; /* Button background */
}
Between Rules
/* Navigation styles */
nav {
display: flex;
}
/* Footer styles */
footer {
text-align: center;
}
At the Top of CSS Files
This is common for metadata.
/*
Project: GK Boost
File: style.css
Author: Dibya Lochan Mendali
Description: Main stylesheet
*/
CSS Comments vs HTML Comments
| Feature | CSS Comments | HTML Comments |
|---|---|---|
| Syntax | /* comment */ | <!-- comment --> |
| Used In | CSS files | HTML files |
| Visible in browser | No | No |
| Purpose | Style explanation | Markup explanation |
⚠️ HTML comments do not work in CSS and vice versa.
Commenting Out CSS Code Safely
One of the most common uses of CSS comments is disabling styles.
Correct Way
/*
.box {
width: 200px;
height: 200px;
}
*/
Incorrect Way (Will Break CSS)
// This is NOT valid in CSS
.box {
color: red;
}
CSS Comments in Inline Styles
CSS comments do NOT work inside inline styles.
This Will NOT Work
<div style="color: red; /* comment */">
Inline styles do not support comments.
CSS Comments in <style> Tag
CSS comments work perfectly inside <style> tags.
<style>
/* Page background */
body {
background: #f5f5f5;
}
</style>
CSS Comments and Minification
During Development
Comments are helpful and recommended.
In Production
Most CSS minifiers remove comments to:
- Reduce file size
- Improve loading speed
Some tools keep important comments marked with !.
/*! Important license comment */
Best Practices for Writing CSS Comments
1. Be Clear and Short
Bad:
/* This does something */
Good:
/* Centers the navigation items horizontally */
2. Comment Sections, Not Every Line
Avoid over-commenting obvious code.
3. Use Section Headers
/* =========================
HEADER SECTION
========================= */
4. Remove Old or Misleading Comments
Outdated comments are worse than no comments.
5. Use Consistent Style
Pick one format and use it everywhere.
Common Mistakes with CSS Comments
- Using
//instead of/* */ - Forgetting to close a comment
- Commenting out large blocks without testing
- Leaving temporary comments in production code
Real-World Example of Well-Commented CSS
/* =========================
GLOBAL STYLES
========================= */
body {
margin: 0;
font-family: Arial, sans-serif;
}
/* =========================
BUTTON COMPONENT
========================= */
.button {
background-color: #007bff;
color: #fff;
padding: 10px 16px;
}
This structure is clean, readable, and professional.
SEO and Performance Impact of CSS Comments
- CSS comments do not affect SEO directly
- Excessive comments may slightly increase file size
- Minified CSS removes comments for faster loading
For blogs and tutorials, comments are valuable.
For live production sites, optimize them.
CSS Comments for Beginners vs Professionals
| Level | Usage |
|---|---|
| Beginner | Learning, understanding code |
| Intermediate | Debugging, organizing |
| Advanced | Documentation, frameworks |
No matter your level, comments are always useful.
Final Thoughts
CSS comments are simple, but their impact is huge.
They make your code:
- Easier to read
- Easier to maintain
- Easier to debug
- Easier to share
Good CSS is not just about styles—it’s about clarity.
And CSS comments are the foundation of that clarity.
Frequently Asked Questions (FAQ)
What are CSS comments?
CSS comments are notes written inside CSS code using /* */ that are ignored by browsers and used only to help developers understand or manage styles.
How do you write comments in CSS?
You write CSS comments by placing text between /* and */.
Example:
/* This is a CSS comment */
Does CSS support single-line comments?
CSS does not have a separate single-line comment syntax. Even single-line comments must use /* */.
Can CSS comments span multiple lines?
Yes, CSS comments can span multiple lines and are commonly used for documentation and section headers.
Do CSS comments affect website performance?
CSS comments do not affect performance directly, but too many comments can slightly increase file size. Minified CSS usually removes them.
Can I use comments inside inline CSS?
No, CSS comments do not work inside inline styles written inside HTML tags.
Are CSS comments visible in the browser?
No, CSS comments are completely ignored by browsers and are not displayed on the webpage.