I’ve been doing some freelance work for a former employer of mine. It’s been an interesting experience to crack open files that I wrote years ago. I’ve always been a firm believer that, if your code doesn’t improve with time, you’re doing something wrong. But, it’s still a disconcerting experience to ask yourself “what dummy wrote this?” and answer, “oh, right, it was me.”
For the most part, I haven’t been questioning my own intelligence. But there’s something about the passage of time (and no longer having access to your old email address) that exposes all the little ways that I could have done things better. Please feel free to point and laugh at me.
An Email is Not Documentation
Who needs a readme or a wiki when you can simply open up your inbox and hit ctrl-f? Me. It’s me who needs that documentation. This is something I think we’re all guilty of. There was a past version of us who spent 2 hours debugging something and then sent an email about it. Honestly, even sending that email is better than nothing. I can’t tell you how many times I’ve done the ctrl-f dance only to read a response like “well, it took me a few hours and a trip to Mordor, but this is working now.”
I always think I’m going to remember the solution, and I almost never remember the solution. I remember all the words to “Rapper’s Delight” but I don’t remember what that error message means.
Write your solutions down, people. And put them somewhere central, so someone who isn’t you can find them.
Write Comments That You With a Head Injury Could Understand
At my last job, I was writing code for other developers to download and use. So, I got used to leaving comments on everything. I would start at the top of a script, work my way down, and explain what was happening to a trusty rubber duck. All of my explanations got added as comments. People tell me that they were useful.
You know what isn’t useful?
function DoTheThing() // this does the thingComments like these make sense while we’re writing them. Of course they do! We just wrote the thing, we remember exactly what the thing does. Will we remember what the thing does five years from now? Will we even remember what the thing is? I’m here to tell you that no, no we will not. Comments are supposed to be for other people, but sometimes they’re for us. In internet parlance, ELI5 (Explain Like I’m 5). Even better, explain like someone is about to hit you over the head with something heavy and then make you find and fix a bug.
In other words, write your comments in plain English.
I just went through the file that I’m working on to see if I could find an inane comment that we can all laugh at. I don’t know if it’s a good thing or a bad thing that I couldn’t find any. I can tell you what I did find, though. Whitespace. Lots and lots of whitespace. An unbroken string of functions with zero comments.
Past Me: I don’t need to comment this, it’s obvious what it does
Present Me: I have no idea what this does
Past Me: It makes sense in context
Present Me: I don’t want to re-read the entire solution, I just want to know what DoTheThing() does
Past Me: That sounds like a “you” problem
Present Me: You are so lucky I don’t have a time machine
(You all have imaginary arguments conversations with yourselves, right?)
Resist the Urge to Get Fancy
Two heads are better than one, and two return types are better than one, right? Sometime, yeah, but not when you have to go back and fix things in two places. I used to add a bunch of extra functions to save myself extra work if the client changed their mind or asked for new functionalities. Now I saw, “that’s what change orders are for.” By all means, add in some little helper functions that will make things easier for you. But don’t try to out-program the client. Anything you add to a program will have to be maintained.
At the same time…
Think Ahead About Updates
You know what I love? When adding another object type (a room, a source, a lighting load, etc) requires copying and pasting in 4 different places with 3 manual updates because find and replace won’t fix them. Did I say love? I meant hate. I like to think of the objects in my program as units. Those units should be able to survive a “by the way.”
“By the way, we never installed those cove lights.”
“By the way, we added a new source in the home theater.”
This would seem to be at odds with my faith in change orders. But this form of defensive programming necessitates making things as simple as possible. Instead of leaving 7 dummy devices in a program because someone might want to add one later, you make it super easy to add a new device. This has an added bonus of making your code more scalable and easier to debug.
“Just write elegant code” is easier said than done, so here are a few tips:
- When in doubt, use a constant. I will sometimes use constants for values that I only ever reference once. If all of your constants live at the top of your script, you can easily make changes. And, with autofill, having a constant in place makes it easier to reference that constant if you add a reference later
- Just because your constants currently share a value, doesn’t mean that they always will. Don’t cross the streams, people! If the only thing that they share is that they’re both currently set to the same number, they should be different. The whole point of a constant is to make it easier to update in one place.
- Loops and dictionaries/lists/array are our friends! If you can add an extra source by tacking on an entry to an array, you’ll be a hero when the client comes to you with a “by the way.” It can be harder to follow something that gets generated by loop (instead of getting hard coded), so make sure you comment like the person takin on the code after you is 5.
The good news is, the newer my past code is, the easier it is to work on. Hopefully, that means I’ve learned a thing or two over time.
Have you ever said “what mouth breather wrote this?” and realized that it was you?
