Comments

In modern web development, comments are messages written exclusively for humans. While browsers completely ignore them during stylesheet parsing, well-crafted comments significantly enhance readability and maintainability, making them an indispensable element of team collaboration.

CSS relies on a single block comment format, bounded by /* at the beginning and */ at the end:

/* This is a single-line comment */
body {
  margin: 0; /* Comments can also follow declarations */
}

/*
  This is a multi-line comment
  that can span across multiple lines.
*/

When working with CSS comments, several crucial rules apply:

• No single-line shorthand: CSS does not support // syntax. Accidentally using // can cause the parser to misinterpret subsequent rules, breaking your layout.
• No nesting: Comments cannot be nested. The parser treats the very first */ it encounters as the end of the comment block.
• Flexible placement: Comments can reside almost anywhere in a stylesheet—between selectors or inside declaration blocks—except inside string literals (e.g., content: "/*" is treated as a string, not a comment).
  Frontend engineers frequently switch between multiple languages, each with its own commenting syntax:

CSS possesses the most restrained commenting system among frontend technologies. It lacks JavaScript's quick // syntax and does not offer the "silent" preprocessor comments that disappear during compilation. Consequently, all comments in vanilla CSS files are shipped directly to the browser and end-users, a factor worth remembering during development.

Typical Use Cases

1. Section and File Division: Place metadata at the top of a stylesheet—detailing purpose, author, and revision history—and use prominent dividers to isolate sections like resets, global variables, and component styles.
2. Explaining "Why": Code shows what is happening, while comments explain why. This is especially vital for browser hacks, quirky compatibility fixes, or seemingly redundant declarations to prevent future developers from breaking them.
3. Collaborative Markers: Employ standard keywords like TODO or FIXME to flag pending tasks for code reviews or global searches.
4. Debugging Assistance: Temporarily commenting out suspicious declarations is a standard diagnostic technique for tracing specificity conflicts and layout issues.
5. Documentation Generation: Some teams adopt structured conventions like KSS to parse comments and automatically generate living style guides.

Here is a comprehensive example incorporating these practices:

/* ========================================
   Buttons Component
   Author: team-fe   Last updated: 2024-06
   ======================================== */

/* TODO: Add hover state styles for dark mode */
.button-primary {
  background: #0066cc;
}

Best Practices and Guidelines

• Focus on intent: Comments should explain the background and rationale rather than translating code line-by-line. Redundant comments like /* Set color */ add clutter without providing value.
• Keep them updated: Always revise comments when modifying code. Outdated comments are far more misleading than having no comments at all.
• Maintain security: Never store sensitive data—such as internal API endpoints or credentials—in CSS comments. Although ignored by browsers, source code remains accessible to anyone inspecting the page.
• Production builds: Build tools typically strip comments to reduce file size. If a license or copyright notice must survive minification, formatting it as /*! Important license notice */ instructs most compressors to preserve it.
• Standardize as a team: Establish a unified style for section dividers and task keywords, incorporating these guidelines into your team's style guide to ensure consistency across large projects.

Conclusion

The comment syntax in CSS is deceptively simple, limited to just /* */, but its value stretches far beyond basic syntax. It serves as both personal memory reinforcement and a contextual bridge for teammates. Whether building complex grid layouts or polishing visual details, adhering to the principles of explaining the "why," keeping text synchronized with code, and protecting sensitive data ensures stylesheets remain robust and maintainable over long-term iterations.