I’ve had a lot to say recently about the right way and the wrong way to write your code. Sure, there are any number of tricks and hacks that you can employ to get your software shipped more quickly. You’re a freaking wizard, after all, slinging bits and bytes with wanton abandon. You’re a master of digital arcana, weaving algorithms that lesser monkeys would look upon and despair. But will you use your power wisely, or succumb to the temptation of the dreaded “quick fix”? Read on for my last two pieces of advice on how to avoid becoming a victim of your own making.
Document Thoroughly
For all that this point should be blindingly obvious, I’m frequently astounded by the fervor of the resistance that I meet when suggesting it. The arguments I’ve had flung at me are many. I’ve been told that it takes too long, that it doesn’t capture information as precisely as the code, and that writing it is just repetition of the code anyway, dismissing it as a waste of effort. I’ve been told that it’s too great an investment to update when the code changes and that incorrect documentation is worse than no documentation, dismissing it as detrimental. And I’ve been told my personal favorite, that it doesn’t matter anyway because the code is “self-documenting”, dismissing it as irrelevant. All this and more I’ve been told by many programmers who should absolutely know better, and whose work I otherwise respect. Whenever I’m told these things, though, I’m reminded of something a classmate once said to me that I think sums up the backing sentiment perfectly: “If I wanted to write documentation, I would have been a damn English major.”
The unfortunate truth is that, yes, documentation is something of a drag to write. It takes time and it’s very easy to do wrong. It can even feel pointless at times, since having the code fresh in your head, after writing or changing it, makes it all so much more clear. And yet? It’s still absolutely necessary to writing maintainable code. Source code is meant to be understood by machines, and takes a lot more time for a person to comprehend than real words. What’s easy for many programmers to forget is that their understanding of those lines of code will fade, and a lot more quickly than they’d like to admit. Even worse, that code may end up being maintained by someone else entirely, who’s never seen it before and doesn’t share the familiarity that comes with building that code in the first place. The worst case is coming on board to a project, cursing whomever wrote that ancient crappy open source library they’re still using, then finally realizing that it was something you wrote ten years ago and don’t remember anymore.
Really, documentation isn’t that hard and the time spent can pay big dividends. For a good place to start, just add a snippet of documentation above each method. Give a brief, sentence-or-two description of what it does. Add a blurb about the parameters it takes and what’s expected of them; number ranges, string formats, nullability, and the like. Describe what’s being returned, if anything. For bonus points, describe its expected error conditions and what it does when it encounters one. Any of this sound familiar? It should. It’s what you need to know in order to respect your interfaces, like I told you two weeks ago. That alone is about 80% of what you really need, and there are plenty of development tools that make it super-easy. When writing Java code in Eclipse, for instance, you can just type “/**” on the line above a method then hit enter, and the editor will automatically fill in a documentation scaffold for you with blanks to fill in for each of the key items. Even better, it will automatically parse the Javadoc that you’ve written and display it to you as a tooltip for future references, allowing quick review of documentation without taking you out of the context in which you’re working.
Manage Your Debt
As with every good rule, there are times when any or all of the things that I’ve told you need to be broken. Occasionally, development speed really is that critical. Maybe the module you’re fixing is slated for replacement in a couple of months anyway (assuming the replacement doesn’t get cancelled, of course). There will times when you need to do things quick and dirty, and that’s okay. What you absolutely must remember, though, is that shortcuts are not free. When you take one you’re incurring technical debt, as that hacky, unmaintainable code will live on far longer than you’d likely care it to. You’re borrowing against your future time to make things go faster now, and believe me when I tell you that technical debt always comes back for its due.
Just like with money, taking on technical debt can let you build things that would otherwise take too long. Eventually, though, you’re going to have to pay off that principal, either by fixing the shortcuts you took or by replacing the whole thing. The longer you wait to pay off your debt, the harder it will be as the code in question grows in usage and spreads to other modules. Also just like with money, you’ll be making payments on that debt in the meantime, having to maintain and fix bugs in code that you’re eventually going to have to stop propping up and fix once and for all. All of this is okay, so long as it’s done with careful consideration as to whether the eventual price is worth the current gain and with a real plan to pay that debt down. Fail to live up to your obligations and you’d better believe you’re getting sent to collections.
One last thing
So there you have it. Three weeks, six good practices to making your code easier to maintain. It takes effort and a modicum of discipline, but even small considerations can yield significant benefit in the long term. Just remember that every line of code you write will live in production long after you’ve moved on. Hell, there are people out there still using Windows 95, and that was published almost two decades ago. It’s not usually feasible to just throw out old code and replace it with something shiny and new; somebody has to maintain it. Just pretend that the person who has to maintain your code for the next twenty years is a psychotic axe murder who knows where you live, and the rest should fall into place.
What do you think? Any best practices that you think I’ve left out? Are these things that you wish the guy before you had known? Got an axe of your own to sharpen? Tell me about it in the comments.
I think all of those objections to documentation can be true*, but that just means the objector needs to write better documentation. If their documentation is just code duplication, they need to write something more useful. Document the why, not the how; as they say.
(* Well, all true except for the bit about self-documenting code. That one’s not even a little plausible.)