There is a misconception that "more comments = better code." This is false. Good code explains *what* is happening. Good comments explain *why* it is happening.
The "What" vs. The "Why"
The "What" (AI Style)
These comments explain the syntax. They are useless to anyone who knows the programming language.
javascript
// Define a constant for the tax rate
const TAX_RATE = 0.08;
// Loop through the items array
for (let i = 0; i < items.length; i++) {
// Multiply price by tax rate
total += items[i].price * TAX_RATE;
}
The "Why" (Human Style)
These comments explain business logic, edge cases, or non-obvious decisions.
javascript
const TAX_RATE = 0.08; // CA state tax as of 2024
for (const item of items) {
// Skip gift cards as they are tax-exempt
if (item.type === 'gift_card') continue;
total += item.price * TAX_RATE;
}
Signs of AI Comments
1. **Header Blocks**: Giant blocks at the top of every file listing "Author", "Date", "Description". (Git handles this history; code doesn't need it).
2. **Docstrings on Getters**: Documenting a function named `getUserName` with "Returns the user's name".
3. **End-of-line Noise**: `</div> <!-- end of container -->`. Modern IDEs highlight matching tags; you don't need this.
The Golden Rule
**If the code is clear, delete the comment.** If the code is complex, try to simplify the code first. Only write a comment if the code *cannot* explain itself (e.g., a weird bug fix or a specific business rule).