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 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.
/* … */. 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.
/* 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.
/*
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.
.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.
.card {
background: #fff;
border-radius: 12px;
padding: 24px;
/* box-shadow: 0 4px 16px rgba(0,0,0,.1); */ /* ← temporarily disabled */
border: 1px solid #e5e7eb;
}
/*
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 */
}
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.
/*
* 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.
/* ══════════════════════════════════
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.
.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:
// support./* multi-line */
/* CSS comment */
// is stripped during compile. /* */ passes through./* comment */
// 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.
/* 80px = fixed navbar height */
/* TODO: */ or /* FIXME: */ so nothing gets forgotten
/* sets the color to blue */ — the code already says
color: blue
// single-line syntax — it is invalid in CSS and
silently breaks the rule
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.
/* ── 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;
}
nav {
display:flex;
align-items:center;
justify-content:space-between;
padding:0 24px;
height:60px;
background:#0f172a
}
/*! (note the
exclamation mark). This is used to keep license headers in the minified output. For
example: /*! normalize.css v8 | MIT License */.
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.
Quick Check — Chapter 4
/* 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.
/* … */ 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.
/* … */ 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).
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.
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
// color: red; inside
a CSS file?- 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.
Rate Us on Google
Join Our Learning Community
Connect with thousands of learners, get daily tips, ask questions and stay updated with new tutorials.
/*
This is a
multi-line comment
*/
h1 {
color: #264de4; /* inline comment beside a declaration */
}