Code Comments: A Blessing or a Curse? ??

We often think adding comments makes our code cleaner and more meaningful. But honestly, it’s not always the case. Too many comments can actually make your code messy, confusing, and frustrating to maintain.

Comments:

A good comment is like a signpost—it guides you without getting in the way. But here’s the kicker: comments should never be your fallback for messy code. If your code is clean, clear, and self-explanatory, you won’t need to write a novel in the comments. Let the code do the talking instead of explaining every little thing.

Bad Comments:

A bad comment is just a crutch. It’s either outdated, redundant, vague, or just plain lazy. Instead of helping you understand the code, bad comments make it harder to read and maintain. For example, when a comment doesn’t match the actual code, it creates confusion and wastes time.

Example:

// Check if the employee is eligible for benefits 

if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))         

vs

if (employee.isEligibleForFullBenefits())         

Which one would you rather read? The second one is clear, concise, and self-explanatory. No comments needed!

Consequences of Bad Comments:

• Outdated comments can mislead you when the code changes but the comment doesn’t, wasting time and spreading misinformation.
• Redundant comments (Comments that simply restate what the code already clearly expresses) clutter your code and add zero value.
• Vague comments (comments that are too general or unclear) leave readers guessing about what the code is doing.
• Bad comments justify messy or poorly written code instead of fixing it.
• Excessive comments disrupt the flow of the code and make it harder to follow.
• Over-commented code creates a dependency on comments, which reduces understanding of the actual code.
• Maintenance overhead increases as comments need to be updated and can become inconsistent.
• Poor comments give a false sense of clarity, making tough code look easier than it is.
• Comments can make you lazy—developers might avoid fixing bad code, thinking the comment is a good enough solution.

Mistakes to Avoid When Adding Comments:

• Vague Explanations:

// All defaults will load if missing.          

This doesn’t explain what “all defaults” means or how it works. It leaves room for confusion.

• Writing Just Because “You Should”: Not every line of code needs a comment. If the code is self-explanatory, let it speak for itself.
• Using Comments to Justify Bad Design: Instead of explaining why your code is messy, clean it up!

// The next section is super complicated, don’t touch unless you have to. 

for (int i = 0; i < x.length; i++) { 

    for (int j = 0; j < y[i]; j++) { 

        process(x[i][j]); 

    } 

}         

Wouldn’t this be better?

for (Item item : items) { 
    item.process(); 
}         

• Commenting Without Context: Comments should explain why, not just what.

// Update the user data 
updateUserData();         

Why are we updating it? What happens if you don’t?

• Overusing TODO Comments: It’s fine to use “TODO” now and then, but overusing it creates a messy codebase. Either fix the issue or set a proper timeline for it.
• Ignoring Comment Placement: A comment in the wrong place is as bad as no comment at all. Place it where it's immediately relevant.
• Writing Overly Long Comments: If your comment needs more than a couple of lines, ask yourself if the code itself can be rewritten to make the comment unnecessary.
• Copy-Pasting Comments: Don’t just copy and paste comments when duplicating code. Check that they still apply to the new context.

When to Add Comments:

Comments aren’t all bad. Here’s when they actually help:

Legal Requirements:

A comment that includes legal information like copyrights, licenses, or disclaimers. These comments are important to protect intellectual property, specify usage rights, or highlight any legal obligations.

/*
 * Adapted from "DataStructures" by Jane Doe.
 * Original repository: https://github.com/janedoe/DataStructures
 *
 * Copyright (c) 2023 Jane Doe
 *
 * Licensed under the MIT License (https://opensource.org/licenses/MIT).
 *
 * This software is provided "as is", without any express or implied warranties.
 */        

Providing Important Context:

A comment that provides useful context about the code, such as explaining a conversion factor, range, or the meaning behind a variable. It adds clarity to make the code more understandable to someone reading it for the first time.

// Conversion factor from Celsius to Fahrenheit 
private static final double CELSIUS_TO_FAHRENHEIT = 9.0 / 5.0; 

// Amount of money in dollars (Range: $1 to $100) 
private double money;         

Warnings for Resource-Intensive Operations:

A comment that warns the developer about potential risks, limitations, or resource-heavy operations that could affect performance or have side effects. These help prevent unintended consequences.

// This method processes large files and might take a long time. 
public void processBigFile() { 
    writeToFile(10000000); 
}         

TODOs for Future Improvements:

A comment that highlights something that needs to be done or improved in the future. It’s like a reminder for the developer to address something later, whether it's a feature or bug fix.

// TODO: Add proper error handling for edge cases.         

Amplifying Non-Obvious Logic:

A comment that adds emphasis or clarification to non-obvious or complex logic in the code. It helps readers understand why a particular approach or solution is being used.

// Trimming spaces is critical; it prevents misalignment issues.  
String trimmed = input.trim();        

The best comment is often the one you didn’t write, because the code was clean enough to speak for itself.

Agree? Disagree? Let’s discuss below! ??