http://geek-and-poke.com/

Can you please comment on that?


During recruitment interviews, I like to ask people how do they understand the concept of clean code. The beauty of this question is that there’s no one correct answer to it. It does show if one cares about writing good code though. And given that there’s a lot of factors that constitute good, clean code there are some that are repeated on most occasions. It’s mainly code formatting and naming functions and variables, but every now and then the comments are mentioned. How many of you write comments in your code? You do? Well then stop please! Sounds controversial? Bear with me!

Why do you need a comment?

Why do you ever need to write a comment? Most of you would probably say — to describe what’s done here, why it’s done this way or another. In other words to explain yourself. And why do you need to explain yourself? Because if there was no comment, code would be difficult to understand. You see where I’m going with this? Only difficult to understand code needs comments. Clean code shouldn’t be like that. One of its traits is to be self-documenting (it’s a cliché — I know, but like a lot of clichés it’s actually right in many cases and has its exceptions). That means, if you read it, you should immediately know what it does. If you feel like it needs explaining most probably it needs a slight refactor rather than a comment.

“The proper use of comments is to compensate for our failure to express ourselves in code.”, Uncle Bob.

We meet again Mr. Pareto

You probably heard of the Pareto principle aka the 80/20 rule. In a way it applies to writing code. 80% of the time you work on it, you read existing code. Only 20% is spent on writing actual lines. That’s a simplification, of course, but I bet most of you would agree when you think about it for a while. That’s why clean code is so important. Creating code, that is understandable without comments will save you and your colleagues tons of time and effort.

How Difficult Code Is To Read Scale:

  • Sh**ty code without comments
  • Sh**ty code with comments
  • Clean code with comments
  • Clean code without comments

I guess you can guess which way does the scale work :)

Chinese whispers

Another reason why you should avoid comments is that they are simply wrong. How can that be, you might ask? Well, yes — when you write it, it probably explains the situation quite well. However, code evolves. Someone might come after you (for whom you actually left the comment in the first place) and make a little change. And then another person does the same, and another… Do they all update the comment? Probably not. Eventually you get a comment that becomes out of date or misleading. That especially happens when you use references that make sense only to a small group of people or is relevant to a specific time frame.

\\ Workaround for issue #6759

After a while, most developers will be scared to touch it :)

Let’s look on the bright side!

Some situations do justify writing a comment. They can be useful for writing TODO’s or use annotations that will boost your IDE experience. Sometimes you might need to amplify the importance of a piece of code or simply explain, why you had to apply some logic, that might seem bonkers, but it was required for example by business requirements.

There’re also documentation comments. These come in handy as well, when used properly and not in a redundant way. I’m not saying don’t use comments at all. Just use them only when they really matter, or make a difference.

Here be dragons

Also, don’t remove them if you’re not sure you have refactored code to the point, it’s understandable without them — you might accidentally put someone in trouble — they might be there as a warning of what is to come… ;)

To comment or not to comment?

In my opinion the best way is to avoid comments, but not at all costs. If you think of a comment you most probably don’t need it. You can extract that little bit of code to a method or a variable and name it nicely. To paraphrase:

Hey, I just met you and this is crazy,
But could that comment, be a function or a variable maybe?

To illustrate, we can have a look at this pseudocode:

// We want to check if user can access this part of the site
if (((user.active === true && user.status === USER_STATUS::premium) || promoCode === 'GOFORIT') && requestedFunction.active === true)
...

or maybe this is more readable:

if(user.canAccess(requestedFunction)) 
...

You don’t need a comment in this situation. Move hard to read code, to dedicated function and having named everything properly, you immediately see what is going on. Now, thinking how to express yourself in code instead of a comment you have not only clearer code, but also one that’s uses more atomic functions, which also makes your code more maintainable in the long run.

However, proper naming is the core element of the whole deal. If you’re going to follow this beautiful path you need to remember, that the name of the variable of the function must describe beyond doubt what it represents or does. Nothing more, nothing less. And don’t get cute. Be precise. Moreover, I would encourage you to think that way, even when you’re not thinking of leaving a comment!

If you’re 100% sure it’s not the case, and this specific situation demands elaboration due to some weird circumstances — go ahead. That’s what they’re for. Just don’t use them as an excuse for writing nasty lines.

You may argue that it’s simply writing good comments vs. shi**y comments. That’s true, but what I’m trying to say is that having a habit of avoiding comments in favor of refactoring is way better for you.

“Always leave the campground cleaner than you found it”, the Boy Scout Rule.

And yes, it’s better to have bad code commented rather than just bad code. But you know what’s even better? Not having bad code! And good code can be spoiled with comments when it doesn’t need them.

It’s like with footnotes in a book. If you read one, and you need to break reading the main text in order to go to a footnote —it kind of slows you down. It reads better if you don’t need to do that, don’t you think? Same applies to comments. The best-case scenario is when you can just read the code and understand it. I’m not saying don’t use them — use them wisely and rarely :)

TL;DR
Use comments wisely. Don’t comment bad code, try to refactor it first, make it understandable without a comment, and use comments only when that approach fails. Make it a habit and you’ll be a better software developer. Otherwise, you might end up with a nasty habit of using comments as an excuse not to make your code clear.

More reading

If what you just read makes sense to you and you’d like to read more on the topic, I would recommend to start with Robert C. Martin’s (aka Uncle Bob) “Clean Code”. It has a whole chapter dedicated to comments and covers many more aspects of writing good code. Also, I’d recommend getting to know SOLID — a great set of rules, that when followed can make your code readable, maintainable and flexible. The ‘S’ stands for Single Responsibility Principle, achieving which can be aided by the way of thinking I tried to present here :)


Thank you for getting this far! I’d love to learn your opinion on this matter, so please leave a comment… ;)