Chapter 3, Episode 3
Comment Your Code!
Why comments matter and how to write effective ones in CSS
Activity: Documenting a complex CSS file
Scene 1: The Uncommented Mystery
CodyMcTweak: Team, I need your help. A coding bootcamp student submitted this CSS file for their portfolio site. The site looks great, but there's not a single comment in the entire codebase.
They're asking for feedback before they submit it for grading. What should we tell them?
:root {
--primary: #3498db;
--secondary: #2ecc71;
--accent: #e74c3c;
--dark: #2c3e50;
--light: #ecf0f1;
--shadow: 0 1px 5px rgba(0,0,0,0.1);
}
* {
box-sizing: border-box;
margin: 0;
padding: 0;
}
body {
font-family: 'Poppins', sans-serif;
color: var(--dark);
background-color: var(--light);
line-height: 1.6;
}
.container {
max-width: 1200px;
margin: 0 auto;
padding: 0 20px;
}
header {
background: var(--primary);
color: white;
padding: 20px 0;
position: sticky;
top: 0;
z-index: 100;
box-shadow: var(--shadow);
}
nav {
display: flex;
justify-content: space-between;
align-items: center;
}
.nav-links {
display: flex;
gap: 20px;
list-style: none;
}
.nav-links a {
color: white;
text-decoration: none;
transition: opacity 0.3s;
}
.nav-links a:hover {
opacity: 0.8;
}
.hero {
height: 60vh;
background: linear-gradient(rgba(44, 62, 80, 0.7), rgba(44, 62, 80, 0.7)), url('hero.jpg');
background-size: cover;
background-position: center;
display: flex;
align-items: center;
justify-content: center;
text-align: center;
color: white;
}
.btn {
display: inline-block;
background: var(--secondary);
color: white;
padding: 10px 20px;
border: none;
border-radius: 5px;
text-decoration: none;
cursor: pointer;
transition: transform 0.3s;
}
.btn:hover {
transform: translateY(-3px);
}
.features {
padding: 50px 0;
}
.features-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
gap: 20px;
}
.feature-card {
background: white;
padding: 20px;
border-radius: 5px;
box-shadow: var(--shadow);
text-align: center;
}
.feature-card i {
color: var(--primary);
font-size: 2rem;
margin-bottom: 20px;
}
@media (max-width: 768px) {
.nav-links {
display: none;
}
.mobile-menu {
display: block;
}
}GrumpyMcTweak: WHAT THE ?! Not a SINGLE comment in this entire stylesheet?! Does this person hate their future self AND all their coworkers?!
This is EXACTLY why every junior dev should be forced to maintain someone else's legacy code for a month before being allowed to write a single line of their own! They'd never skip comments again!
TrashyMcTweak: Oh look, another "self-documenting code" genius who thinks their variable names are so intuitive that mere mortals should bow down in understanding. Let me guess, they also believe in Santa Claus and that people actually read Terms of Service?
Sure, the code works now. But check back in six months when they've forgotten what --accent was supposed to be used for or why .hero needs that specific height. Have fun reverse-engineering your own thought process, Einstein!
Scene 2: Why Comments Matter
AllyMcTweak: Let's be constructive here. Code comments serve multiple important purposes:
- They explain WHY code does something, not just what it does
- They help others understand your thought process
- They remind your future self why you made certain decisions
- They document browser-specific hacks or workarounds
- They create logical sections in larger files
Remember: code is read far more often than it's written, so optimize for readability!
FattyMcTweak: The premium developers always know that good comments are like signposts on a highway. They don't tell you how to drive, but they make sure you don't miss your exit!
In CSS specifically, comments can explain:
- What specific variables are for
- The purpose of complex selectors
- Why certain magic numbers were chosen
- Which sections correspond to which page components
- Dependencies between seemingly unrelated styles
/* This is a CSS comment */
/*
This is a
multi-line
CSS comment
*/
body {
color: black; /* Inline comment */
}
GarbageMcTweak: People always argue about comment density. Some say "everything should be commented" while others say "only comment when necessary." The truth is somewhere in between.
Don't comment the obvious like /* Sets text color to blue */ next to color: blue; — that's just noise. But do explain the non-obvious, like why you're using z-index: 9999 or why that 13px margin is critical.
Also, use structured comment blocks to divide your CSS into logical sections. It's like putting chapter titles in a book — makes it way easier to find what you're looking for.
Scene 3: The Great Comment Addition
CodyMcTweak: Let's actually improve this code by adding appropriate comments. I suggest we add:
- A header comment explaining the file's purpose
- Section comments to organize related styles
- Variable documentation
- Notes for any complex or non-obvious code
- Brief explanations for media queries
Who wants to start?
/***************************************
* PORTFOLIO SITE STYLESHEET
* Author: Rookie Coder
* Version: 1.0
*
* CONTENTS:
* 1. Variables & Reset
* 2. Base Styles
* 3. Layout & Grid
* 4. Navigation
* 5. Hero Section
* 6. Features Section
* 7. Media Queries
***************************************/
/* 1. VARIABLES & RESET
============================== */
:root {
--primary: #3498db; /* Blue - Main brand color */
--secondary: #2ecc71; /* Green - Call to action */
--accent: #e74c3c; /* Red - Highlights/Alerts */
--dark: #2c3e50; /* Dark blue - Text color */
--light: #ecf0f1; /* Light gray - Background */
--shadow: 0 1px 5px rgba(0,0,0,0.1); /* Subtle shadow */
}
* {
box-sizing: border-box;
margin: 0;
padding: 0;
}
/* 2. BASE STYLES
============================== */
body {
font-family: 'Poppins', sans-serif;
color: var(--dark);
background-color: var(--light);
line-height: 1.6;
}
/* 3. LAYOUT & GRID
============================== */
.container {
max-width: 1200px;
margin: 0 auto;
padding: 0 20px;
}AllyMcTweak: Great start! The file header immediately tells anyone opening this file what it's for and how it's organized. The table of contents makes it easy to jump to specific sections.
And I love how the color variable comments explain what each color is used for, not just what color it is. That's exactly the kind of context that helps maintainability!
Let's continue with the next sections...
/* 4. NAVIGATION
============================== */
header {
background: var(--primary);
color: white;
padding: 20px 0;
position: sticky; /* Keeps header visible when scrolling */
top: 0;
z-index: 100; /* Ensures header stays above other content */
box-shadow: var(--shadow);
}
nav {
display: flex;
justify-content: space-between;
align-items: center;
}
.nav-links {
display: flex;
gap: 20px;
list-style: none;
}
.nav-links a {
color: white;
text-decoration: none;
transition: opacity 0.3s;
}
.nav-links a:hover {
opacity: 0.8;
}
/* 5. HERO SECTION
============================== */
.hero {
height: 60vh; /* 60% of viewport height */
/* Semi-transparent overlay to make text readable on any background image */
background: linear-gradient(rgba(44, 62, 80, 0.7), rgba(44, 62, 80, 0.7)), url('hero.jpg');
background-size: cover;
background-position: center;
display: flex;
align-items: center;
justify-content: center;
text-align: center;
color: white;
}
/* Call-to-action button */
.btn {
display: inline-block;
background: var(--secondary);
color: white;
padding: 10px 20px;
border: none;
border-radius: 5px;
text-decoration: none;
cursor: pointer;
transition: transform 0.3s;
}
.btn:hover {
transform: translateY(-3px); /* Slight upward shift on hover */
}TrashyMcTweak: Much better! At least now when this developer inevitably abandons web development to pursue their dream of becoming a professional kazoo player, the poor soul who inherits this code won't have to perform a digital séance to understand it.
I particularly like the explanation of why the z-index is set to 100 and not, say, 99 or OVER 9000!! These are the kinds of decisions that seem obvious when you're writing them but become complete mysteries three weeks later.
/* 6. FEATURES SECTION
============================== */
.features {
padding: 50px 0;
}
/* Auto-responsive grid - adjusts columns based on available width */
.features-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
gap: 20px;
}
.feature-card {
background: white;
padding: 20px;
border-radius: 5px;
box-shadow: var(--shadow);
text-align: center;
}
.feature-card i {
color: var(--primary);
font-size: 2rem;
margin-bottom: 20px;
}
/* 7. MEDIA QUERIES
============================== */
/* Mobile navigation styles - hamburger menu appears below 768px */
@media (max-width: 768px) {
.nav-links {
display: none; /* Hide desktop navigation */
}
.mobile-menu {
display: block; /* Show hamburger menu */
}
}
/*
* TODO: Add styles for:
* - Contact form section
* - Footer
* - Dark mode toggle
*/GarbageMcTweak: I added a TODO comment at the end. These are super useful for marking unfinished work. Some developers also use FIXME: for known bugs that need addressing.
Many code editors specifically highlight these keywords and can generate task lists from them. It's like leaving notes for your future self or teammates about what still needs work.
GrumpyMcTweak: This is... acceptable. At least now someone looking at this code won't waste HOURS trying to figure out why certain decisions were made.
The section headers make it easy to find what you're looking for without having to scroll through the entire file. This kind of organization becomes even more important as stylesheets grow larger.
Scene 4: CSS Comment Best Practices
FattyMcTweak: Now that we've added comments, let me share some premium best practices for CSS documentation:
- Use a consistent comment style throughout your project
- Create logical sections with header comments
- Explain the "why" more than the "what"
- Document any browser-specific hacks
- Keep a change log for major updates
- Use consistent indentation in multi-line comments
- Consider using a CSS documentation tool like KSS or Nucleus
/* Basic Section Comment
============================== */
/**
* Block Documentation Comment
*
* A more detailed explanation of a complex selector or component.
* Can include multiple lines and formatting.
*/
/* TODO: Add mobile styles */
/* FIXME: Causes layout issue in Firefox */
/* HACK: IE11 fallback */
/* Changelog:
* v1.2 - 2023-09-15: Added dark mode support
* v1.1 - 2023-08-20: Fixed mobile navigation issues
* v1.0 - 2023-08-01: Initial release
*/AllyMcTweak: Remember that comments are meant to enhance readability, not detract from it. Over-commenting can be just as problematic as under-commenting.
I recommend focusing comments on these key areas:
- File overview & organization
- Purpose of complex or non-obvious code
- Known issues or limitations
- Dependencies between components
- Any performance considerations
Anything obvious from reading the code itself doesn't need a comment.
Scene 5: The Verdict
CodyMcTweak: Great work, team! We've improved this CSS file tremendously by adding thoughtful comments. Let's summarize our feedback for the student:
Feedback for Student:
Your CSS code is functionally excellent, but was missing crucial documentation. We've added comments to demonstrate how proper documentation:
- Makes code more maintainable for yourself and others
- Provides clear organization through section headers
- Explains non-obvious choices and techniques
- Creates a roadmap for future development
Remember, writing code that works is only half the job. Writing code that others (including your future self) can understand and maintain is equally important!
TrashyMcTweak: I still think they should be forced to maintain a 10-year-old WordPress theme with 15,000 lines of uncommented CSS as punishment, but I suppose your constructive feedback works too.
Tell them that well-commented code is the difference between being the hero developer everyone wants to work with and being that person everyone curses under their breath whenever they have to touch your code.
GrumpyMcTweak: Just make sure they understand that code comments aren't OPTIONAL. They're part of being a PROFESSIONAL developer.
And if they don't start commenting their code properly, they can look forward to a LIFETIME of being the person assigned all the worst legacy code maintenance tasks because no one trusts them with greenfield projects!