Search posts, tags, users, and pages
Newbie developers have a lot of cringeworthy moments, in the process or transitioning into tech we've all said or done things that still make us cringe when we remember it. One of such moments for me relates to commenting on code. Developers attach c...
olabayobalogun.hashnode.dev2 min read
Markdown supported · ⌘↵ to post
Ben Hammond
Denver Dev && Song Builder
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:
"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.
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!