Syntax
Use /* comment text */. CSS comments can span multiple lines.
Platform under construction
CSS Comments
CSS comments help future readers understand intent, but they should explain decisions instead of repeating what the code already says.
/* Explain why this rule exists. */
.button:focus-visible {
outline: 3px solid #8cffc1;
}
CSS Basics
Comments should explain why, not narrate the obvious.
CSS comments start with /* and end with */. Anything inside is ignored by the browser.
Good comments are useful when the reason behind a rule is not obvious: a browser workaround, an accessibility decision, a layout constraint or a design-system boundary.
Bad comments repeat the property name, leave dead code behind or become outdated. In CSS, outdated comments are dangerous because they make the stylesheet feel less trustworthy.
No nesting
Do not put one CSS comment inside another CSS comment.
Intent
Explain why a rule exists when the code alone does not say enough.
Cleanup
Remove old commented-out code before production.
Visual model
Make the invisible browser work visible.
CSS becomes easier when you can see the parts: what is selected, what is declared, what the browser loads and what the final interface receives.
/* Keep focus visible for keyboard users */
Examples
Good CSS is readable, intentional and easy to change.
Comment explains the decision
/* Keep focus visible because this button has a custom background. */
.button:focus-visible {
outline: 3px solid #8cffc1;
outline-offset: 4px;
}
/* Header is sticky only on screens with enough vertical space. */
@media (min-height: 760px) {
.site-header { position: sticky; top: 0; }
}
Comment repeats or hides noise
/* Make the text red */
.error { color: red; }
/* old button maybe use later
.button { background: purple; padding: 90px; }
*/
Rules that matter
Use these rules before memorizing more properties.
Beginners often try to learn CSS by collecting declarations. That is backwards. Learn the decisions first, then the properties become much easier to remember.
Explain constraints
Comment browser fixes, accessibility choices, design tokens and surprising layout values.
Avoid obvious narration
Do not write comments that only restate the property name.
Use section markers carefully
A short comment can make a long file easier to scan, but too many markers become clutter.
Remove dead CSS
Commented-out CSS is not a version-control strategy. Git already remembers old code.
Keep comments current
A wrong comment is worse than no comment.
Do not leak secrets
Never place internal tokens, private URLs or sensitive notes in CSS comments.
Production thinking
CSS quality shows up in trust, accessibility and speed of change.
Why does this matter?
CSS can become large quickly. Comments are one of the few ways to preserve reasoning, but only if they carry information that the code cannot express by itself.
Accessibility
Comments are useful for protecting accessibility rules. A clear note can prevent someone from removing focus outlines or reducing contrast later.
Production note
Production CSS can keep useful comments, but remove experiments, TODOs without owners and commented-out alternatives.
SEO note
Comments are not visible content for SEO. Their value is maintainability, which indirectly helps the quality of the site over time.
Live code lab
Change the CSS and watch the interface respond.
The preview runs in an isolated iframe. Links and forms stay inside the practice area, so you can experiment without leaving the lesson.
Mini assignment
Try this now.
- Add one comment that explains why a value exists.
- Add one bad obvious comment, then remove it again.
- Add a focus style comment so another developer knows not to remove it.
Practice assignment
Do this before moving to the next lesson.
- Write three CSS comments for real reasons, not property descriptions.
- Remove all commented-out old CSS from your example.
- Explain which comments should stay in production and why.
Try it yourself
Add helpful CSS comments without creating noise
Self-check
Before you continue, prove that you understand CSS Comments.
Do not only read the lesson. Answer these questions out loud or write the answers in your own notes. CSS becomes real when you can explain what the browser is doing.
- Can you write the CSS comment syntax from memory?
- Can you explain why CSS comments cannot be nested safely?
- Can you tell the difference between a helpful comment and noise?
- Can you identify a comment that should be deleted before production?
- Can you use comments to protect an accessibility decision?
Senior audit upgrade
Comments are for source files, not decoration.
Production builds often minify CSS. Comments may disappear, so comments should explain intent for developers before build time, not carry information users need.
Explain why
Use comments for decisions, constraints and warnings, not for repeating the next declaration.
Minification
Do not rely on CSS comments being visible in production output. Build tools usually strip them.
Keep notes close
Place the comment near the rule it protects, especially for accessibility or browser-support decisions.
Explains an accessibility reason.
Repeats "set color red" above color: red.
Commented-out old CSS can hide dead decisions.
Section labels can help in long CSS files.