The One Development Tip That Saves My Butt

Past Brian was a bit of an idiot. Let's try to make Future Brian a bit happier.

The One Development Tip That Saves My Butt
Photo by Daniel Hu / Unsplash

I've worked on a ton of different projects in the 25+ years that I've been programming (yikes, has it really been that long?!). Most projects are just excuses to fool around with a new technology that's come out. They're proof-of-concept throwaways, opportunities to learn, a case of "let's see what this thing can do".

After I've spent a month or so on those projects, they get pushed into source control and will never see the light of day again. And that's okay; they've served their purpose but can also be a reference in the future if I ever need to work with those technologies again.

I do, however, have a few projects that I revisit over and over again. And getting everything back up and running is usually a pain.

Why? Because Past Brian was an idiot.

Well, calling Past Brian an idiot isn't fair. Past Brian meant well, just as Present Brian probably means well by writing in the third person.

The problem was I would see the code and not know why I did something a particular way. I'd see an issue, see the code that's causing that issue, and realize that I don't know why I wrote that code in the first place.

Every line of code I write – every statement, every method, every character – I put there with intention. It has a reason. It exists as part of a whole to solve a problem.

The challenge is that while the code remains, my state of mind isn't preserved. What was I reading about a year ago? What was the issue I was trying to solve? What defect was I patching? It's impossible to remember all of that.

My solution to this is simple: any time I have to do any sort of research for how to implement something, comments go in the code explaining things.

Sometimes it's a simple "As per <url>, if we run into this situation, do <X> then <Y>". Maybe it's simply explaining why I've imported a specific library (this burned me two days ago).

Other times it warrants a more in depth writeup. Those that have worked with me have probably run into my (infamous?) "Hammer Time Comments", which explained why some really janky code was written, that I knew that it was bad, and (perhaps most importantly) that I was sorry.

It's important to apologize for your transgressions.

I started deliberately doing this about three years ago. Now, any time I look at code I don't understand because of it being poorly documented, it's because the code is more than three years old, guaranteed. So I do my best to document it, commit the comments, and move on.

It does mean that I end up writing more. Sometimes it might be overkill. But Present Brian can't know if it will be or not: only Future Brian can.

And Present Brian would really prefer if Future Brian swore at him less.


My Weekly Finds

My People
The Beaches · Song · 2022
Something a little more upbeat than last week. You can't not want to dance along to this!
Ever wonder what’s inside a Tesla battery? Check out these CT scans of Lithium-ion, LiPo, and alkaline batteries.
Learn how Li-ion and LiPo batteries move so many electrons without having to open one yourself. Our CT scanner lets you see inside while staying safe.
Scan Of The Month is one of those websites where everything – and I mean everything – is absolutely fascinating. The presentation of every day objects, the information they provide, and the site design just blows me away. 
Sound – Bartosz Ciechanowski
Interactive article explaining how sound works.
This is a long read, but another great interactive article. So much information about sound, music, and the physics behind it!
GitHub - rbaron/b-parasite: 🌱💧 A Bluetooth Low Energy (BLE) soil moisture sensor.
🌱💧 A Bluetooth Low Energy (BLE) soil moisture sensor. - GitHub - rbaron/b-parasite: 🌱💧 A Bluetooth Low Energy (BLE) soil moisture sensor.
I've been dying to do something like this for years, but I was resigning myself to having everything wired. I may still do that in some areas where I have power close by, but this seems like a great option where that's not viable.

My Weekly Wiki Updates