CSS Comment Syntax – How to Write Comments in CSS | Complete Beginner's Guide (2026-27)

✅ What Is a CSS Comment?

A CSS comment is a piece of text inside your CSS file that the browser completely skips when rendering the page. Comments are only meant for humans — developers reading or maintaining the code. They are invisible to website visitors on the page, though they can be seen in the browser's DevTools or View Source.

CSS comments serve four main purposes:

• ✔️ Documentation – Explain what a section of CSS does and why.
• ✔️ Organization – Label sections of a large stylesheet (e.g., "/* === HEADER === */").
• ✔️ Debugging – Temporarily disable CSS rules without deleting them.
• ✔️ Collaboration – Leave notes for teammates, or for your future self.

✅ CSS Comment Syntax

There is only one comment syntax in CSS. It uses a slash-asterisk opening and an asterisk-slash closing:

✅ Single-Line CSS Comments

A single-line comment in CSS is simply a /* ... */ that fits on one line. You can place it above a rule, beside a property, or anywhere inside the stylesheet.

✔️ Example 1 – Comment Above a Rule

/* Style all headings */
h1 {
  color: #1E3A5F;
  font-size: 28px;
}

✔️ Example 2 – Inline Comment Beside a Property

p {
  font-size: 16px; /* base body font size */
  line-height: 1.7; /* improves readability */
  color: #333; /* dark gray, softer than pure black */
}

✔️ Example 3 – Section Label Comment

/* ============================================
   NAVIGATION STYLES
   ============================================ */
nav {
  background: #1E3A5F;
  padding: 15px 20px;
}

✅ Multi-Line CSS Comments

A multi-line comment uses the same /* ... */ syntax but spans several lines. This is useful for writing longer explanations, file headers, or documentation blocks.

✔️ Example – File Header Comment

/*
  Stylesheet: main.css
  Project: LearnToSAP Tutorial Site
  Author: Pramod Behera
  Last Updated: June 2026
  Description: Main styles for the tutorial layout,
               typography, and component library.
*/

✔️ Example – Multi-Line Explanation

/*
  We use a max-width of 900px on article.page-content
  to keep line lengths readable on wide monitors.
  Research shows 60–80 characters per line is optimal
  for reading comprehension.
*/
article.page-content {
  max-width: 900px;
  margin: 0 auto;
}

✅ Using Comments to Disable CSS Code

One of the most powerful uses of CSS comments during debugging is "commenting out" a rule — wrapping it inside /* ... */ to temporarily disable it without deleting it. This lets you quickly see whether a specific rule is causing a layout problem.

✔️ Example – Commenting Out a Property

h1 {
  color: red;
  /* font-size: 48px; */ /* disabled for testing */
  font-weight: bold;
}

✔️ Example – Commenting Out an Entire Rule

/*
.sidebar {
  float: right;
  width: 300px;
  background: #f5f5f5;
}
*/

✅ Types of CSS Comments – Overview Table

✅ Best Practices for CSS Comments

Writing good comments is a skill. Here are the professional habits that will make your stylesheets clean, maintainable, and team-friendly:

✔️ 1) Comment the Why, Not the What
The code already shows what it does. A good comment explains why that choice was made.

/* z-index must be higher than the modal overlay (z-index: 999) */
.tooltip {
  z-index: 1000;
}

✔️ 2) Use Section Headers in Large Files
In stylesheets longer than 200 lines, always add section headers so anyone can jump to the right part instantly.

/* ============ RESET ============ */
/* ============ TYPOGRAPHY ======= */
/* ============ LAYOUT =========== */
/* ============ COMPONENTS ======= */
/* ============ UTILITIES ======== */

✔️ 3) Mark TODOs and FIXMEs

/* TODO: replace magic number with a CSS variable */
.hero {
  margin-top: 73px;
}

✔️ 4) Remove Comments Before Production (Minify)
Comments add bytes to your CSS file. Always run your CSS through a minifier (e.g., cssnano, CleanCSS) before deploying to production. This strips all comments automatically.

✔️ 5) Keep Comments Up to Date
An outdated comment is worse than no comment — it actively misleads the reader. When you change a rule, update or remove its comment.

✅ Common Mistakes to Avoid

✅ CSS Code Example – Comments in Action

Here is a complete, real-world CSS file showing how professionals use comments at every level — file header, section labels, inline notes, and debugging comments:

✅ Try It Yourself – Interactive CSS Comment Editor

Edit the HTML and CSS below to experiment with CSS comments. Try adding your own, commenting out a rule, or writing a section header. The preview updates automatically.

✅ Practice – Yes / No Quiz

✅ Frequently Asked Questions (FAQ)