I’d wrapped up some pretty complex logic in a massive 100 line if-else statement. Ambiguous variables were everywhere: var credit, var otherCredit, var creditTransfer, var transferCredit. And the functions, oh the functions! They were long and horrendous to read through. It’s as if I wanted conserve variable names by slamming as much logic as I could into each set of curly braces.
I now see the err of my ways and hopefully you can learn from my mistakes. Some lessons I’ve taken away from that months-long refactor of my old code were:
Var Names Matter
If you’re reading this, you’re likely new to the world of JS. Maybe you’re writing variables like var x or var y. Don’t do that. Take the time to give your variables meaningful, unique names. This can seem trivial at first, maybe there are only a handful of vars in your app in the first place. Well, that’s what I thought too, until the scope of my project increased tenfold over its duration. I was also wary of using variables with names that were too long. I regret this. Better to have a descriptive, long name for a variable (ex: catWithBlackHair) than a short ambiguous one (ex: cat). A variable should yield no surprises. If the name of var or function ever makes you scratch your head a little, it will make you want to pull your hair out six months from then, when you’re knee deep in a refactor.
Your Functions Should Be Shorter
That twenty line js function you wrote that takes in a user’s input, does some UI update, makes an ajax request and then does another update… well, you may want to change that up. I know it works now but think ahead, far ahead. When your PM, you or some external force causes you to change the logic in that function. Well, now you’re in a game of code jenga, where refactoring part of that massive function may break the rest. Keep your functions small. How small? They should really just do one thing. ‘Doesn’t this mean I will have a lot of functions?’ Well, yeah, but that can be OK. You will greatly increase the readability of your code by abstracting logic into small functions and you will also decrease the potential for duplicating the same code when you have many small functions. Do two different ajax requests update the UI? Great, have a function they can share to do this rather than duplicating those lines within each request.
Comment that Shit
A year is a long time. Reading through my old code was like reading a novel written by a drunk version of myself. I mean, I vaguely remembered writing it, but it seemed so foreign, so incomprehensible, so dumb… A wiser me would have left a trail of breadcrumbs explaining some of the more difficult parts of the code and why I was doing what I was doing where I was doing it. Short and sweet functions and descriptive var names would have greatly enhanced the readability as well but I was batting 0 for 3 here. If you follow the first two pieces of advice here you shouldn’t need to rely on comments for another dev to follow what’s going on in the story you’re weaving through code, but good comments, especially those explaining things that may provide insight to the business logic or why an odd choice was made will be invaluable in the future and probably prevent you from having one of those ‘Oh, so that’s why she left that function in the code’ moments, after a deployment blows up in your face.
If you want to take a deep dive into writing good, clean code, check out this book.