How to Include Comments in CSS Code (With Best Practices)

When writing CSS, comments are a simple yet powerful tool that help you make your code easier to read, maintain, and collaborate on. Whether you’re working solo or with a team, leaving meaningful comments in your CSS can save time and reduce confusion.

In this blog post, we’ll cover:

• ✅ How to write comments in CSS
• 🎯 When and why to use comments
• 🧠 Best practices for writing helpful comments
• 🚫 Common mistakes to avoid

---

✅ How to Write Comments in CSS

CSS uses a simple syntax for comments:

/* This is a CSS comment */

🔹 Example:

/* Header Styles */
header {
  background-color: #f9f9f9;
  padding: 20px;
}

• Comments start with /* and end with */
• They can span multiple lines
• CSS ignores them during rendering

❌ Invalid Comment Syntax

// This is not valid in CSS (it's used in JavaScript)
#main {
  color: black;
}

❗ Important: Always use /* */ for CSS comments — not //.

---

🎯 Why Use Comments in CSS?

Here’s why comments are helpful in CSS:

Benefit	Description
🧭 Improved readability	Makes large files easier to scan and understand
🤝 Better collaboration	Helps teammates understand your thought process
🛠 Easier debugging	Mark out specific sections when troubleshooting
📁 Code organization	Use headings to divide sections logically

---

🧩 Common Use Cases

1. Section Headings

/* === Navigation Bar === */
.navbar {
  background: #333;
  color: white;
}

2. Explaining Specific Rules

/* Adding spacing between form elements for better UX */
form input + input {
  margin-top: 12px;
}

3. Temporarily Disabled Code

/*
.button {
  background: red;
}
*/

You can “comment out” code without deleting it.

---

🧠 Best Practices for CSS Comments

1. ✅ Be concise and clear
   • Avoid over-explaining obvious code.
2. ✅ Use consistent formatting
   • For example: /* === Section === */ or /* --- Layout --- */
3. ✅ Comment why, not just what
   • Instead of just saying /* Button style */, say /* Primary button for call-to-action */
4. ✅ Avoid clutter
   • Don’t comment every single line — it defeats the purpose.

---

📦 Example: Well-Commented CSS

/* === Global Styles === */
body {
  font-family: 'Inter', sans-serif;
  background-color: #f0f2f5;
  margin: 0;
}

/* === Header Section === */
header {
  /* Sticky top navigation */
  position: sticky;
  top: 0;
  background-color: #fff;
  z-index: 1000;
}

/* === Footer === */
footer {
  padding: 20px;
  text-align: center;
  color: #777;
}

---

🚫 Common Mistakes to Avoid

Mistake	Why It’s a Problem
❌ Too many obvious comments	Adds noise, not value
❌ Using JavaScript-style //	Not valid in CSS
❌ Leaving outdated comments	Can mislead future developers
❌ Using comments as “dead code” long-term	Keep your CSS clean and up-to-date

---

✅ Summary

Action	How to Do It
Write a comment	/* Your comment here */
Add section headers	/* === Section Name === */
Comment out code	Wrap code inside /* */

Comments in CSS are simple, but when used thoughtfully, they significantly enhance the readability and maintainability of your code.

---

🚀 Final Thoughts

Don’t treat CSS comments as an afterthought. Use them intentionally to guide yourself and others through your stylesheets — especially in large or shared codebases. A well-commented CSS file can be just as important as clean HTML or JavaScript.