Why Code Comments Should Be Your Best Friend (If They’re Not Already…)

Photo by Luca Bravo on Unsplash

Today I learned an important lesson about doing things to help out my future self. I was revisiting some old projects, cleaning them up and making sure they’re working properly, and I quickly realized that I am not as familiar with these apps as I was when I was working with them daily (DUH). In order to add some very minor features to the apps, I first had to spend quite a bit of time re-familiarizing myself with the functions I had written and what they do, something that, in hindsight, I could have easily avoided. Take this block of code, for example:

app.js

I spent a substantial amount of time tracking down where these functions were coming into play, distinguishing them between similarly-named functions, and realized after talking with a friend that had I used comments to explain what purpose they served, I could have expedited the work I was doing on this project.

Now take a look at this updated code block, including comments to explain beyond specific function names what the code is accomplishing:

updated app.js

Including comments in your code is a quick way to make your life easier when you’re returning to projects you haven’t looked at in a while. Not only that, being descriptive in your code will also help any colleagues or fellow coders who may look at your code at some point.

I’ve learned today that although it seems annoying to take the time to write comments as you’re writing your code, it’s a small effort with a huge benefit. Future you will thank you!