Course contentsShow
← Software Engineering
Lesson 377 of 1,93311. Code Quality and ReadabilityFree lesson

Comment Anti-Patterns

Identify harmful comment patterns: redundant comments, outdated comments, commented-out code, and noise comments.

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.