Comments In Css

Master the art of writing effective CSS comments that improve code maintainability, facilitate team collaboration, and streamline debugging workflows.

Comments are one of the most underrated yet powerful tools in a CSS developer's toolkit. They serve as a communication bridge between you and your future self, your teammates, and anyone else who might work with your codebase. Whether you're building a small personal project or maintaining a large-scale application with thousands of lines of CSS, understanding how to write effective comments is essential for professional-grade code that stands the test of time.

What Are CSS Comments?

CSS comments are annotations embedded directly within your stylesheets that provide information, explanations, or context about the code they accompany. Unlike regular CSS rules that browsers parse and apply to elements, comments are completely ignored during rendering. They exist solely for human readers—developers who need to understand the purpose, logic, or history behind specific styling decisions.

The CSS comment syntax follows a simple pattern that has remained consistent since the language's inception. Comments begin with a forward slash followed by an asterisk (/*) and end with an asterisk followed by a forward slash (*/).

The CSS Comment Syntax

Single-Line Comments

Single-line comments occupy a single line within your stylesheet and are typically used for brief explanations or notes. While CSS doesn't have a dedicated single-line comment syntax like JavaScript's //, you can achieve the same effect by wrapping your comment text between /* and */ markers on a single line.

Single-line CSS comment example

1/* This is a single-line comment */2.button {3  background-color: blue; /* Inline comment explaining this choice */4}

Multi-Line Comments

Multi-line comments extend across multiple lines and are ideal for longer explanations, notes, or temporarily disabling sections of code during development. The syntax remains the same—you simply continue the comment across lines until you reach the closing */ marker.

Multi-line CSS comment example

1/* This comment spans2 multiple lines and can contain3 extensive explanations */4.card {5  border: 1px solid #ddd;6  border-radius: 8px;7}

Section comment organization example

1/* ==========================================2   GLOBAL STYLES3   Base styles, resets, and CSS custom properties4   ========================================== */5 6/* ==========================================7   TYPOGRAPHY8   Font definitions, text styles, and headings9   ========================================== */10 11/* ==========================================12   COMPONENTS13   Reusable UI components (buttons, cards, forms)14   ========================================== */

Search-friendly section markers example

1/* || RESET AND BASE STYLES */2 3* {4  margin: 0;5  padding: 0;6  box-sizing: border-box;7}8 9/* || TYPOGRAPHY */10 11h1, h2, h3 {12  font-family: 'Inter', sans-serif;13  line-height: 1.2;14}

Debugging with comments example

1/* Temporarily disabled to test layout issue2.card {3  display: grid;4  gap: 1rem;5}6*/

Common comment patterns examples

1/* IE11 flexbox fix: min-height not working correctly2   See: https://github.com/philipwalton/flexbugs#flexbug-3 */3 4/* Using design token: --color-primary-500 from theme */5background-color: var(--color-primary-500);6 7/* TODO: Refactor this component styling when design system updates land */

Ready to Build Better CSS?

Our web development team specializes in creating maintainable, scalable stylesheets using modern best practices.

Frequently Asked Questions

Can I use HTML comments in CSS files?

No, HTML comments (``) cannot be used in external CSS files or within `<style>` tags. CSS only supports the `/* */` comment syntax. HTML comments were historically used for CSS hacks in older browsers but this practice is obsolete.

Do CSS comments affect page load performance?

No, CSS comments have no runtime performance impact. Modern browsers strip comments during parsing, and build tools typically remove comments when optimizing stylesheets for production.

Should I comment every CSS rule?

No, you should not comment every rule. Focus on explaining the 'why' behind non-obvious decisions rather than describing what the code already clearly shows. Over-commenting creates noise that reduces readability.

What's the best way to organize large CSS files?

Use section comments to divide your stylesheet into logical groups (reset, variables, typography, components, utilities, etc.). Consider breaking very large stylesheets into multiple smaller files that are imported as needed.