Comment by Ben Hammond on "Newbie developers and cringeworthy moments"

I’m going to push back on the “code should explain itself” concept for newbies; there is ZERO harm in literally commenting every single line of code, and I’d actually encourage it as a way of truly learning... if that code is something you’ve copy pasted or done as part of a tutorial’s starting code.

Comments can always be easily deleted later; trying to figure out a complex bit of uncommented code takes much more time.

So yes, best practices dictate only commenting where needed. But as beginners the comments WILL be needed much more frequently than they will be for a senior dev, and that is all good!

// embrace the comments!

You make a great point. Commenting can be done on personal projects, just not collaborative projects where you will be reviewed.

Yes, good distinction OLABAYO BALOGUN

I'm going to push back on your push back.

There are situations where comments are necessary e.g. commenting on the intent of the code, warning of consequences or clarifying the purpose of the code (I would refer to Bob Martin's Clean Code for examples on these).

However when writing production code on your own projects / other projects you should get into the practice of writing code that can be understood without comments. This is for a number of reasons:

Comments are just another piece of code that needs to be maintained. I've seen many situations where the code and comments didn't match because the developer changed something and forgot to update the comments.
It promotes lazy variable / function naming: instead of writing down what the functionality does in a comment, you should try to think about how to write the code in a way where the comment isn't needed.
It adds a lot of noise. When I'm reviewing or working on code, I don't want to be looking at comments. I want to be looking at code.

"Trying to figure out a complex bit of uncommented code takes much more time."

You have picked up on one of the key elements of clean code - managing complexity. If you're looking at some code, and you don't understand what's going on it usually means that the code isn't written cleanly and the correct abstractions haven't been used.

Writing legible code is difficult but it's an incredibly important part of software engineering.

I would recommend reading Bob Martins Clean Code and also a philosophy of software design by John Ousterhout.

Sloth I mean, sure. But the article is Newbie developers and cringeworthy moments; I feel very strongly that the last thing a newbie learning how to code should worry about is if their comments will be embarrassing or offend the code gods. Just get the thing working! Learn! Play! Have fun! Add in any comments you need to understand how the code is really working.

Then, once you are writing production code and presumably not a newbie, all of Sloth‘s advice definitely applies.

And of course, as you’re learning your goal should be to understand the language and constructs so well that you won’t need any comments to yourself anyways.

Search Hashnode