Comments in CSS

Comments in CSS are notes written inside a stylesheet for developers. The browser ignores comments when applying styles, so comments do not change the visual output of the page. Their job is to make CSS easier to understand, organize, explain, and debug. A good comment can save time when returning to a stylesheet after weeks or months.

CSS comments are simple, but beginners often confuse them with comments from other languages. CSS uses /* to start a comment and */ to end it. JavaScript-style // comments are not standard CSS comments and should not be used in normal CSS files.

CSS Comment Syntax

The correct syntax for a CSS comment is shown below.

/* This is a CSS comment */

Everything between the opening /* and closing */ is treated as a comment. The browser skips it while processing the stylesheet.

/* Style for main article paragraphs */
p {
  color: #333333;
  line-height: 1.6;
}

In this example, the comment explains the purpose of the rule. The paragraph style still works normally because the comment is separate from the declaration block.

Single-Line Comments in CSS

CSS does not have a separate single-line comment symbol. A short comment still uses the same block-comment syntax.

/* Primary button */
.button-primary {
  background-color: blue;
  color: white;
}

This is called a single-line comment only because the opening and closing comment markers are on the same line. The syntax is still a CSS block comment.

Multi-Line Comments in CSS

CSS comments can also span multiple lines. This is useful for section labels, longer explanations, or notes about design decisions.

/*
  Card component
  Used on blog listing pages and related post sections.
*/
.card {
  padding: 24px;
  border: 1px solid #dddddd;
  border-radius: 8px;
}

Multi-line comments are helpful when a stylesheet is divided into sections. They make it easier to scan the file and jump to the part that needs editing.

Why Comments Are Used in CSS

• To label sections of a stylesheet.
• To explain why a rule exists.
• To document browser-specific fixes.
• To temporarily disable CSS while debugging.
• To leave notes for future maintenance.
• To separate global styles, layout styles, component styles, and utility styles.

The best comments explain intent, not the obvious. A comment saying sets color to red above color: red adds very little value. A comment explaining why an unusual rule exists can be extremely useful.

Good CSS comments explain the reason behind a rule, especially when the rule looks unusual or exists to fix a specific layout problem.

Using Comments to Organize CSS

In larger stylesheets, comments can work like headings. They help separate base styles, typography, layout, components, forms, utilities, and responsive rules.

/* =========================
   Base Styles
   ========================= */

body {
  margin: 0;
  font-family: Arial, sans-serif;
}

/* =========================
   Card Component
   ========================= */

.card {
  padding: 24px;
  background-color: white;
}

This style of section comment is common because it creates clear visual breaks in long files. It does not affect the browser output, but it improves developer navigation.

Using Comments for Debugging

Comments can temporarily disable CSS declarations or full rules while debugging. This helps test whether a rule is causing a layout or visual issue.

.box {
  width: 300px;
  /* height: 300px; */
  background-color: lightgray;
}

Here, the height declaration is commented out. The browser ignores it, but the code remains in the file. This is useful during testing, but old commented-out code should not stay forever. Too many disabled rules make a stylesheet messy and confusing.

CSS Comments vs HTML Comments

CSS comments and HTML comments use different syntax. HTML comments look like <!-- comment -->. CSS comments look like /* comment */. Using the wrong type in the wrong file can break code or produce invalid output.

Language	Comment Syntax	Example
CSS	/* comment */	/* Button styles */
HTML
JavaScript	// comment	// Update menu state
JavaScript	/* comment */	/* Multi-line note */

If CSS is written inside a <style> tag, it still uses CSS comment syntax. The surrounding file is HTML, but the code inside the style tag is CSS.

Do Not Use Double Slash Comments in CSS

The // style is not normal CSS comment syntax. Some preprocessors such as Sass support single-line comments, but regular CSS does not treat them as standard comments.

/* Correct CSS comment */
.title {
  color: navy;
}

// Wrong in normal CSS
.subtitle {
  color: gray;
}

If you write // in a regular CSS file, the browser may ignore part of the rule or parse it unexpectedly. Always use /* */ for CSS comments.

Comments and Minification

In production websites, CSS is often minified. Minification removes extra whitespace and may remove comments to reduce file size. This means comments are mainly for source files, not for what the user downloads in the final optimized CSS bundle.

Some comments that start with /*! are preserved by certain build tools because they may contain license information. Normal project notes are usually removed during production builds.

/*! License information may be preserved by some tools */

Comments and Security

Never place passwords, private tokens, secret URLs, admin notes, or sensitive business information inside CSS comments. Even if comments do not appear visually on the page, CSS files can often be viewed by visitors through browser developer tools or direct file URLs.

Comments should explain code, not store private data. If a note would be risky for a visitor to read, it does not belong in a public stylesheet.

Good CSS Comment Examples

/* Use border-box so component widths include padding and border */
* {
  box-sizing: border-box;
}

/* Extra offset prevents the sticky header from covering anchor targets */
.section {
  scroll-margin-top: 90px;
}

These comments explain why the rules exist. The second comment is especially useful because the rule may look strange without context. A future developer can understand the reason and avoid deleting it accidentally.

Bad CSS Comment Examples

/* color blue */
.link {
  color: blue;
}

/* margin bottom 20px */
.title {
  margin-bottom: 20px;
}

These comments repeat what the code already says. Repeating obvious declarations increases noise without improving understanding.

Best Practices for CSS Comments

• Use comments to explain why, not just what.
• Use section comments to organize long stylesheets.
• Remove old commented-out code after debugging.
• Do not store sensitive information in comments.
• Use correct CSS comment syntax everywhere in CSS files.
• Keep comments updated when the related CSS changes.

Outdated comments can be worse than no comments because they mislead the next person reading the file. If a rule changes, update or remove the related comment.

Comments Inside Media Queries

Comments are also useful inside responsive CSS. Media queries often contain overrides that only apply at certain screen widths. A short comment can explain why a breakpoint exists, especially when it is based on a design layout instead of a common device size.

/* Cards become two columns when each card has enough readable width */
@media (min-width: 760px) {
  .card-grid {
    grid-template-columns: repeat(2, 1fr);
  }
}

This comment explains the design reason behind the breakpoint. It is better than a comment that simply says “tablet styles” because device sizes change, but the readability reason remains clear.

Team-Friendly Comment Habits

In a team project, comments should help the next person make safe changes. If a rule depends on a plugin, a browser bug, a third-party widget, or a layout limitation, write that context near the rule. Without that note, another developer may delete the rule because it looks unnecessary.

Comments should also stay close to the code they explain. A note at the top of a large file can become disconnected from the rule it describes. Keeping comments near the related selector reduces confusion and makes future cleanup easier.

When Comments Should Be Removed

Comments are not permanent just because they were once useful. Temporary debugging comments, old TODO notes, and disabled code should be cleaned up before the stylesheet becomes stable. A stylesheet full of old comments becomes noisy, and important comments are harder to notice.

A simple rule is this: keep comments that explain current design intent, browser behavior, or maintenance context. Remove comments that explain removed features, abandoned experiments, or obvious declarations.

Comments for Browser Fixes

Sometimes CSS contains a rule that exists only because of a browser behavior, a third-party plugin, or a layout edge case. These rules need comments more than normal styles. Without context, a future edit may remove the rule and bring back the original bug.

/* Prevent long code lines from breaking the article layout */
.wp-block-code {
  overflow-x: auto;
}

The declaration is simple, but the reason matters. The comment explains that the rule protects article layout when code examples are wider than the content area. That is more useful than a comment that says “adds overflow.”

Comments in Generated or Third-Party CSS

Avoid editing generated CSS files directly if a build tool, theme, or plugin recreates them. If you must inspect generated CSS, add comments in the source file instead of the output file. Otherwise, the next build may erase your note along with your change.

For third-party CSS, prefer writing override comments in your own stylesheet. Mention the component or plugin being overridden and why the override is needed. This keeps custom project decisions separate from vendor code.

This is especially useful in WordPress themes and plugins, where generated class names and plugin styles may change after updates. A short note can explain which plugin behavior the override is protecting.

That note prevents accidental cleanup from breaking the page later.

Comments in CSS FAQ

What is the correct comment syntax in CSS?

CSS comments start with /* and end with */. The browser ignores everything between those markers.

Can I use // comments in CSS?

No. Double slash comments are not standard CSS comments. Use /* */ in normal CSS files.

Do CSS comments show on the web page?

No. CSS comments do not render visually, but the CSS file may still be visible to visitors through developer tools.

Should I remove comments before publishing CSS?

Build tools often remove normal comments during minification. Keep useful comments in source CSS, but do not rely on comments to hide private information.

---