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.

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.