Comment Anti-Patterns
You'll learn: How to recognize and avoid common harmful commenting practices that clutter code and create maintenance problems.
The Dark Side of Comments
Not all comments are helpful—some actively harm code quality. Just as we've learned to identify code smells, we need to recognize comment anti-patterns: commenting practices that waste time, mislead developers, or make code harder to maintain.
Four Major Comment Anti-Patterns
Redundant Comments
Comments that simply restate what the code obviously does:
# Increment counter by 1
counter = counter + 1
# Check if user is active
if user.is_active:
These comments insult the reader's intelligence and add visual noise without value.
Outdated Comments
Comments that were once accurate but no longer match the code:
// Returns the user's email address
public String getUserPhoneNumber() {
return this.phoneNumber;
}
The danger: Developers trust comments and make wrong assumptions, leading to bugs.
Commented-Out Code
Dead code left "just in case":
function processOrder(order) {
// const discount = calculateDiscount(order);
// order.applyDiscount(discount);
return order.total;
}
This creates confusion ("Why was this removed? Should I restore it?") and clutter. Version control systems preserve history—use them instead.
Noise Comments
Comments that state the obvious or add no information:
// Constructor
public User() {}
// Default value
private int count = 0;
These are visual clutter that developers learn to ignore, training them to skip all comments—including important ones.
Why These Matter
Comment anti-patterns create maintenance debt. Redundant comments must be updated alongside code. Outdated comments mislead. Commented-out code breeds uncertainty. Noise comments train developers to ignore documentation entirely.
Key Takeaway: Recognize and eliminate redundant, outdated, commented-out, and noise comments—they actively harm code quality by cluttering your codebase and eroding trust in documentation.