Comments are always failures. Their purpose is to compensate for our failure to express ourselves in code.

-- Robert C. Martin, author of "Clean Code" book.

But why are they that bad you ask? Aren't comments used to clarify our code & make complicated things clearer?

Yes, they surely are. But many many times, comments cause more harm than good.

Let me explain:

1) Comments are NEVER a replacement for clean & readable code.

I actually feel like writing this line 3 more times due to how important it is... 😅

If you write a mess of a code, then writing a comment that explains what this mess does is not the good solution, it's the lazy one. The good solution is to clean up this mess & re-write this code to be as readable & self-explanatory as possible.

Rename your variables, rename & create new smaller functions, use constants instead of hard-coded values, etc.

2) Comments rot VERY quickly.

What does that mean?? It means that the code we have, & the comment that supposedly explains this code can (and will) get out of sync very quickly. Because code changes & evolves a lot.

Some part gets extracted to a function. Variables renamed. The algorithm used changed. Or many other things.

But let me ask you this: Are comments usually maintained & updated each time some part of the code changes?

Most of the times, no...

Which leads us to the 3rd and most important point

3) Comments LIE 😈

When the code & comment are out of sync, then reading the comment will only mislead & confuse the developer.

Because the comment will give him some certain assumptions & expectations about the behaviour of the code, but running the code, produces "wrong" results!!

So there will need to be a long debugging session for the developer to figure out the reason of the unexpected results.

4) Comments are hard to clean

When you see a piece of code with an old comment that someone else wrote, will you have the courage to delete it even if you half-believe it's old & not needed anymore??

Chances are, you will not... Neither will the other devs. Because we think: "maybe it's important to someone else..."

The Fix

So how can we write good comments then??

Here's the trick: A good comment is a no-comment. 😇

You should try your best to get rid of all the comments you can, while still keeping the code clear.

So I'll now provide you with the top 3 strategies that could help you with that!

1) Improve your variables names.

This is probably the most important tip!!

Because once your variables names are good, your code will read naturally without needing any comments.

What makes a variable name "good" you ask??

It should be:

• Easily readable
• Reveal its intended purpose (Very important)
• Makes sense in its usage context

Avoid:

• Using an abbreviation unless it's still very clear.
• Appending a number to the end of the var name.
• Using 1 letter variable unless their scope is very small.

2) No 3-in-1 function, make them 3-in-3 functions 😂

When you see a comment explaining what a function is doing, then it's very likely that this function is doing several different things. Why is that?? Because a function doing multiple things is usually:

• Hard to find a meaningful proper name that describes properly everything this function do.
• No clear distinction between the different parts

So instead of having a function like:

validatePreprocessSendConfirmPayment() that does 4 things,

Make it:

validatePayment();
preprocessPayment();
sendPayment();
confirmPayment();

3) Prefer constants over Magic numbers

Magic numbers are any number hardcoded directly into your code statements. Something like:

realSalary = salary - (salary * 0.05) + 2000;

Is it clear to you what these 0.05 or 2000 are?? Nope, neither me.

So instead of writing a comment beside them explaining what they are, extract them into constants:

realSalary = salary - (salary * TAXES_PERCENT) + YEARLY_BONUS;

Much clearer, isn't it??

So in summary:

1. Use good variables names
2. Make small functions that do only one thing
3. Extract hard-coded values into constants

Final Note

It's worth noting that although comments are bad in most cases, there are still a FEW places where comments are inevitable. Where even clean code won't be able to express why a certain edge case is handled in a certain way, or why this wierd thing is being done,...etc. But most of the times, they should be removable.

And that's everything guys!! It was a long article, but you made it to the end, so Congrats to you!!

Until next time, And have an awesome day 👋