Comments in Code: Why Less is Often More

Okay, okay, I know—this might sound obvious, but hear me out. There’s an old saying among developers: “If the code is well-written, it doesn’t need comments.” And there’s a lot of truth to that. Often, comments—especially redundant ones—only clutter the code and distract from what’s actually going on.

Good code should speak for itself. The structure, variable names, and function names should be so clear that it’s obvious what the code is doing. If we find ourselves needing to explain in comments what each line does, maybe the code itself needs some love and refactoring.

Of course, exceptions exist—like when you’re working with complex logic or unique algorithms. But for the most part, clean, logical code minimizes the need for constant explanation.

Let’s look at a few examples:

Redundant Comments:

// Set counter to 1
let counter = 1;

// Add 1 to counter
counter += 1;        

This is a classic case of comments explaining what the code already makes clear. No need to state the obvious here.

Useful Comments:

// Using a hash map to store unique items for faster lookup
const itemsMap = new Map();

// Complex calculation for determining optimal price
// Formula based on historical data and adjusted monthly
let optimalPrice = calculateOptimalPrice(data, month);        

In this case, the comments provide context that’s not immediately clear from the code itself. They give insight into the why, rather than the what, which makes them much more valuable.

Here are a few ways to write code that speaks for itself:

1. Use meaningful variable and function names that convey purpose (yes, “x” is rarely helpful).

2. Organize code into logical blocks and modules so it’s easy to follow without commentary.

3. Only add comments when they actually add value—we don’t need a “this function adds 1” label above every line, right?

So, while comments have their place, let’s make them rare and valuable. Otherwise, we might as well be writing a novel alongside our code. ??