Beginner-Friendly Topic
Take your time - it's perfectly normal to re-read this topic 2-3 times. Try the interactive code editor below to run code yourself. Use the Q&A section to check your understanding before moving on. You've got this! 🚀
CSS Comments & Best Practices
CSS comments help you and your team understand your code. Combined with good formatting practices, comments make stylesheets maintainable. This topic covers comment syntax, when to use comments, and CSS formatting conventions.
Comment Syntax & Practices
- /* comment */ - The only comment syntax in CSS. Works for single-line and multi-line
- Section headers - Use comments to divide your CSS into logical sections: /* === HEADER === */
- Explain why, not what - Don't write /* make text red */ for color: red. Write /* brand color for errors */
- TODO comments - /* TODO: fix mobile layout */ marks work that needs attention later
- Consistent formatting - One property per line, indent with 2 or 4 spaces, blank line between rules
- Property order - Group related properties: positioning → display → box model → typography → visual
- Avoid unused CSS - Remove styles you're not using. Dead CSS slows page loads and confuses developers
Well-Organized CSS
/* ================================
GLOBAL STYLES
================================ */
/* Reset */
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
/* Base typography */
body {
font-family: Arial, sans-serif;
font-size: 16px;
line-height: 1.6;
color: #333;
}
/* ================================
COMPONENTS
================================ */
/* Card component */
.card {
background: white;
border-radius: 12px;
padding: 24px;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
/* TODO: add dark mode variant */
}Tip
Adopt a consistent property order convention from day one. A recommended order: position/display properties first, then box model (width, padding, margin), then typography (font, color), then visual (background, shadow). This makes scanning CSS much faster.
The cascade determines which style wins when multiple rules conflict
Common Mistake
Using // for comments in CSS doesn't work - it's JavaScript syntax. CSS only supports /* */ block comments. Writing // will cause the browser to misread your styles and silently break rules below the comment.
Quick Quiz
Key Takeaways
- CSS comments help you and your team understand your code.
- /* comment */ - The only comment syntax in CSS. Works for single-line and multi-line
- Section headers - Use comments to divide your CSS into logical sections: /* === HEADER === */
- Explain why, not what - Don't write /* make text red */ for color: red. Write /* brand color for errors */