Skip to main content
HashnodeBeginner's safe space.

Command Palette

Search for a command to run...

Newbie developers and cringeworthy moments

Published
•2 min read
Newbie developers and cringeworthy moments
O
Olabayo Balogun

A technical writer and .Net software engineer who is committed to building technological infrastructures capable of solving the challenges of netizens now and in the future.

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 comments to their code (like people do for documents that they review), the machine doesn't read or act on a developer's comment.

I once thought to add comment for every line of code I write thus translating everything I write to English. Why this is ridiculous is that when best practices are followed, code is supposed to be self commenting, which means you should write your code in a way that is easy enough for the next developer to understand. Comments are mostly used to explain the logic behind some processes and to provide strict instructions/guidelines to other developers that will peek under the hood of said project. Thankfully I never got to write the kind of comment I had in mind before I learnt industry best practices. I shudder to think about what would have happened if ended up writing such a code, having to review and defend it in public.

As a newbie in tech you have to mentally prepare yourself for the fact that you'll get many things wrong and you maybe laughed at or reprimanded for it. What matters is that you pick yourself up and keep moving, you may not quickly notice it but you are getting better.

#learning#learn-coding#learning-journey#learn#codenewbies

Comments (1)

Join the discussion
B
Ben Hammond5y ago

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!

2
O
Olabayo Balogun5y ago

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

1
B
Ben Hammond5y ago

Yes, good distinction OLABAYO BALOGUN

S
Sloth5y ago

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.

1
B
Ben Hammond5y ago

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.

More from this blog

Beginner's safe space.

352 posts

A blog that accompanies budding software engineers in their journey by making them realize that they're not alone and their challenges doesn't stop them from making a career in software development.