Tutorials CSS CSS Comments
Ch 4 / 60
Chapter 4 Beginner 3 min read CSS

CSS Comments

Comments are notes you leave inside your CSS that the browser completely ignores. A well-commented stylesheet is a gift to your future self — and to every developer who will ever read your code.

What you'll learn
The only CSS comment syntax: /* … */
Single-line vs multi-line comments
Inline comments beside a declaration
Commenting out code while debugging
Section dividers and file headers
Comment best practices and what to avoid

What is a CSS Comment?

A CSS comment is any text placed between /* and */. The browser's CSS parser reads right past it — comments have zero effect on how your page looks or behaves. They exist purely for humans.

Comments can explain why a rule exists, mark sections of a large stylesheet, temporarily disable code while debugging, or leave reminders for future work.

/* This entire line is a comment — the browser ignores it completely */
/*
  This is a
  multi-line comment
*/

h1 {
  color: #264de4; /* inline comment beside a declaration */
}
Only one syntax
CSS has only one comment syntax: /* … */. Unlike JavaScript or many other languages, CSS does not support double-slash // … single-line comments. Writing // color: red; in CSS will simply break that declaration — the browser won't throw an error, it will silently ignore the entire rule.

Single-line & Multi-line Comments

Although CSS has only one comment syntax, you can use it in a single-line or multi-line form depending on how much you need to write.

Single-line Comment

Open and close on the same line. Perfect for brief explanations or inline notes beside a declaration.

CSS
/* Reset default browser margin */
body {
  margin: 0;
}

h1 {
  font-size: 2rem; /* 32px at default browser font size */
  color: #264de4;  /* brand blue */
}

.btn {
  border-radius: 8px; /* design token: --radius-sm */
}

Multi-line Comment

Span across as many lines as you need. Ideal for block descriptions, file headers, or longer explanations.

CSS
/*
  This rule handles the hover state of all primary buttons.
  It adds a subtle shadow and a 2px upward lift to indicate
  that the element is interactive.
  Last updated: 2025-07 — changed shadow colour to match brand.
*/
.btn-primary:hover {
  transform:  translateY(-2px);
  box-shadow: 0 8px 24px rgba(38, 77, 228, 0.4);
}

Inline Comment (beside a declaration)

You can place a /* … */ comment on the same line as a CSS declaration — after the semicolon. This is great for tagging magic numbers or clarifying non-obvious values.

CSS
.hero {
  padding-top:  80px;  /* 80px = navbar height */
  z-index:       10;  /* must stay below modal (z: 100) */
  line-height:  1.15; /* tighter for display headings */
  opacity:         1;  /* overrides .fade-in (0) on load */
}

Commenting Out Code — Debugging Trick

One of the most useful things you can do with comments during development is temporarily disable a rule or declaration without deleting it. This lets you quickly test "what happens if this rule is gone?" and easily restore it by removing the comment markers.

CSS — Commenting out a single declaration
.card {
  background:    #fff;
  border-radius: 12px;
  padding:       24px;
  /* box-shadow: 0 4px 16px rgba(0,0,0,.1); */ /* ← temporarily disabled */
  border:        1px solid #e5e7eb;
}
CSS — Commenting out an entire rule block
/* 
  Commenting out the entire animation rule
  to test if it's causing the layout shift.

.hero-image {
  animation: fadeInUp 0.6s ease forwards;
}

*/

.hero-image {
  /* animation: fadeInUp 0.6s ease forwards; */
  opacity: 1; /* fallback while animation is disabled */
}
VS Code shortcut
In VS Code, select any CSS lines and press Ctrl + / (Windows/Linux) or Cmd + / (Mac) to instantly toggle a /* … */ comment. This works in the editor's CSS mode. It is the fastest way to comment/uncomment code while debugging.

Section Dividers & File Headers

As stylesheets grow, comments become an essential navigation tool. Professional developers use section dividers and a file header to organise large CSS files so any team member can jump to the right place instantly.

File Header

A comment block at the very top of your stylesheet documents what the file does, who wrote it, and other useful metadata.

CSS — File header comment
/*
 * style.css
 * Main stylesheet for K2infocom website
 *
 * Author:   K2infocom Team
 * Version:  2.4.0
 * Updated:  2025-07
 *
 * Table of Contents:
 *   01. CSS Variables & Reset
 *   02. Typography
 *   03. Layout & Grid
 *   04. Navigation
 *   05. Hero Section
 *   06. Cards & Components
 *   07. Forms
 *   08. Footer
 *   09. Utilities
 *   10. Media Queries
 */

Section Divider Comments

Use visually distinct comment blocks to separate major sections. The pattern below makes it easy to scan a long file at a glance.

CSS — Section dividers
/* ══════════════════════════════════
   01. CSS VARIABLES & RESET
════════════════════════════════════ */

:root {
  --blue: #264de4;
  --radius: 8px;
}

* { box-sizing: border-box; margin: 0; padding: 0; }


/* ══════════════════════════════════
   02. TYPOGRAPHY
════════════════════════════════════ */

body { font-family: Arial, sans-serif; font-size: 16px; }

h1, h2, h3 { line-height: 1.2; }


/* ── Sub-section within Typography ── */
h1 { font-size: clamp(1.8rem, 4vw, 3rem); }
h2 { font-size: clamp(1.4rem, 3vw, 2.2rem); }


/* ══════════════════════════════════
   03. LAYOUT & GRID
════════════════════════════════════ */

.container { max-width: 1200px; margin: 0 auto; padding: 0 24px; }

TODO & FIXME Tags

Many teams use tagged comments to flag work-in-progress items. Most code editors and IDEs can highlight these automatically.

/* TODO: replace magic number with CSS variable */
.sidebar { width: 260px; }

/* FIXME: z-index conflict with the modal — causes click-through */
.dropdown { z-index: 50; }

/* NOTE: this transition intentionally matches the JS animation duration */
.overlay { transition: opacity 0.3s ease; }

/* HACK: IE11 fallback — remove when IE11 support is dropped */
.grid { display: flex; /* display: grid not supported in IE11 */ }

CSS Comments vs Other Languages

If you already know another language, it is important to know that CSS uses a different comment syntax. Here is how CSS compares:

CSS
/* comment */
Only one syntax. No // support.
JavaScript
// single line
/* multi-line */
Both styles work in JS.
HTML
<!-- comment -->
Different syntax entirely. Don't mix them up.
Sass / SCSS
// silent comment
/* CSS comment */
// is stripped during compile. /* */ passes through.
Python
# comment
Hash comments — completely different from CSS.
SQL
-- comment
/* comment */
Both styles supported in most SQL dialects.
Common mistake
Beginners who know JavaScript often try // color: red; in CSS. The browser does not throw an error — it silently ignores the malformed line. The declaration is simply lost with no visible feedback, which can cause hours of confusing debugging.

Good vs Bad Comment Practices

Comments add value when they explain the why — not the what. The what is already visible in the code itself.

Write comments that explain WHY
Explain why a magic number or hack exists: /* 80px = fixed navbar height */
Document browser-specific workarounds with a reason and when to remove them
Use section headers in large stylesheets so teammates navigate quickly
Flag work-in-progress with /* TODO: */ or /* FIXME: */ so nothing gets forgotten
Note intentional design decisions that might look wrong to a new developer
Avoid comments that state the obvious
Avoid /* sets the color to blue */ — the code already says color: blue
Don't leave large blocks of commented-out dead code in production — it confuses readers and bloats the file
Don't use // single-line syntax — it is invalid in CSS and silently breaks the rule
Avoid outdated comments that no longer match the code — wrong comments are worse than no comments
Never commit sensitive information (API keys, passwords, internal URLs) inside comments

Comments & CSS Minification

CSS comments are completely invisible to the browser — they never affect how your page renders. However, they do add bytes to your CSS file.

In production, CSS is usually run through a minifier (e.g. cssnano, clean-css, or your build tool like Vite or Webpack). Minifiers strip all comments and whitespace, reducing file size by up to 30–50% on comment-heavy stylesheets.

CSS — Before minification (development)
              
 /* ── Navigation ── */
nav {
  display:flex;           /* horizontal layout */
  align-items:center;         /* vertically centre links */
  justify-content:space-between;  /* logo left, links right */
  padding:0 24px;
  height:60px;           /* matches --nav-h variable */
  background:#0f172a;
}

CSS — After minification (production)
              
nav {
  display:flex;
  align-items:center;
  justify-content:space-between;
  padding:0 24px;
  height:60px;
  background:#0f172a
}
              
              
Special preserved comments
Some minifiers preserve comments that start with /*! (note the exclamation mark). This is used to keep license headers in the minified output. For example: /*! normalize.css v8 | MIT License */.
Free Resource
CSS3 Cheat Sheet — All Properties & Selectors
One printable page covering every CSS3 property, selector type, unit and layout system. Perfect quick reference for beginners and intermediate developers.
Download PDF

Try It Yourself

The editor below shows comments used in all four ways at once — as a section header, inline annotation, multi-line explanation, and debugging comment-out. Try uncommenting the box-shadow line and watch the card change.

Live Editor
✎ Editor
👁 Preview
Featured Course — Enroll Now
Modern Web Development With AI
Master HTML, CSS, JavaScript, React and Node.js — all in one industry-ready curriculum. Build real projects with AI-powered tools and get placement support.
120+
Chapters
40 hrs
Content
10 Real
Projects
4.9 ⭐
Rating
HTML5 CSS3 JavaScript React.js Node.js Tailwind CSS AI Tools

Quick Check — Chapter 4

Questions & Answers
CSS comments use the block comment syntax: opening with /* and closing with */. Everything between these two markers is ignored by the browser. This works on a single line or across multiple lines.

Example: /* This is a valid CSS comment */

CSS does not support // … double-slash comments. Writing // color: red; silently breaks that declaration without any error message.
No. CSS only supports the /* … */ syntax. The // syntax is not part of the CSS specification.

However, you can achieve a "single-line" comment by opening and closing on the same line: /* this is effectively a single-line comment */.

Note: Sass/SCSS does support // as a "silent comment" — but it strips those during compilation so they never appear in the output CSS. Plain CSS never supports it.
Wrap the declaration or rule block with /* … */ to "comment it out". The browser ignores everything inside, so the style is disabled without being deleted.

Single declaration: /* box-shadow: 0 4px 16px rgba(0,0,0,.1); */

Entire rule: wrap the opening /* before the selector and */ after the closing brace.

To quickly toggle this in VS Code, select the lines and press Ctrl+/ (Windows/Linux) or Cmd+/ (Mac).
CSS comments have no effect on rendering — the browser's CSS parser skips them entirely. A comment next to color: blue; will not change the colour at all.

However, comments do slightly increase file size. In development this is fine, but in production CSS files are usually minified — all comments and whitespace are stripped by a build tool (cssnano, Vite, Webpack, etc.) to produce a smaller file for faster page loads.

Special exception: comments starting with /*! are preserved by most minifiers — used to keep licence headers in output files.
The golden rule: comment the why, not the what. The code already shows what it does.

Good practices:
— Explain magic numbers: /* 80px = fixed navbar height */
— Use section headers to navigate large stylesheets
— Tag work-in-progress with /* TODO: */ or /* FIXME: */
— Document intentional quirks or browser-specific hacks

Avoid:
— Obvious comments: /* makes the text blue */
— Leaving large blocks of commented-out dead code in production
— Outdated comments that contradict the current code
— Sensitive data (API keys, passwords) inside comments
Multiple Choice Questions
Question 1 of 5
Which of the following is the correct CSS comment syntax?
Question 2 of 5
What happens if you use // color: red; inside a CSS file?
Question 3 of 5
Which comment tag is typically preserved by CSS minifiers?
Question 4 of 5
What is the VS Code keyboard shortcut to toggle a CSS comment?
Question 5 of 5
Which of the following is a good use of a CSS comment?
Chapter Summary
  • CSS has one comment syntax only: /* … */. Double-slash // is invalid in CSS and silently breaks any rule it touches.
  • Comments can be written on a single line, across multiple lines, or inline beside a declaration — all using the same /* */ markers.
  • Comments have zero effect on rendering — the browser completely ignores them. They exist for developers, not browsers.
  • Use comments to comment out code while debugging — wrap rules with /* */ to disable them without deleting. Toggle quickly with Ctrl+/ in VS Code.
  • Section dividers and file headers make large stylesheets navigable. Use /* TODO: */ and /* FIXME: */ tags to flag work-in-progress.
  • Comment the why, not the what. Avoid stating the obvious; document magic numbers, browser hacks and intentional design decisions.
  • CSS minifiers strip all comments in production. Comments starting with /*! are preserved for licence headers.
~3 min read
Beginner level
Chapter 4 of 60

Rate Us on Google

4.8 / 5
Enjoying this tutorial?
Your 5-star review helps other learners discover our free tutorials and encourages us to keep creating quality content.
80+ reviews
Write a Google Review
Join WhatsApp Channel