Verdant Artifice

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.

Last week I started talking about a few of the practices that go into writing solid, maintainable code.  Throwing together layer upon layer of hacks in order to get an application or feature out the door more quickly can be very tempting.  Often it will even appear to have been the right choice, at least for a little while.  After all, if it works for you and your customer/boss gives the nod, you can always go back later and take care of those bugs you swept under the rug, right?  The fact is, though, that most of the time that rug never gets looked under again.  Problems are left to fester, because there’s more profit and satisfaction in developing new software than maintaining existing code.  Writing code to be more easily maintained, and as a by-product need less maintenance in the first place, is a difficult skill.  It requires a greater expenditure of time and an adherence to discipline that can seem overly restricting, but the time and headache that you save yourself later make it all worthwhile.

Be Boring

Shortcuts aren’t the only pitfall waiting to ensnare would-be code-monkeys as they hack their way through a jungle of logic.  More dangerous by far is the trap that you bring with you: cleverness.  See, the dirty little secret about writing computer software is that a lot of it is dead boring.  Your typical programmer is an intelligent person that needs a certain level of mental challenge and stimulation in order to maintain interest in his or her job.  Simply getting the job done isn’t always enough; there has to be a puzzle to solve or a new tool to explore or the simple joy of hearing your peers say, “How did you do that?!”  Unfortunately, opportunities for these career-validating experiences can be few and far between, particularly when so many potential employers think the world really needs is another e-commerce website from which to sell widgets.

In an environment like that, when confronted with the dull reality of the job, many programmers will make the terrible mistake of being clever.  If the end product is boring, we’ll make the implementation of that product “interesting”.  Instead of using a known, existing tool that does what we need we’ll build our own from scratch.  When we could get the job done simply by using known design patterns, we’ll instead opt to spend hours upon hours weaving tangled threads of logic into tortured knots.  And the whole time we’ll tell ourselves all kinds of lies about how we’re just trying to make our code more elegant or optimized, when all we really want is something to sink our mental teeth into.  Don’t fall into this trap.  The satisfaction you get in the short term from admiring your own cleverness will tarnish very quickly in the face of the extra debugging sessions brought on by an over-complicated design and implementation.  Take it from me: it’s not worth it.

Expect Failure

One of the most common mistakes that I see when reading code, whether it was written by a novice fresh out of school, a veteran with dozens of languages under his or her belt, or even myself just five years ago, is the assumption that things will work as expected.  Error codes will be left unchecked.  Exceptions will be left uncaught.  Return values will be left unvalidated.  I suppose I can’t blame them, really.  Building a complex piece of software is difficult, even when everything goes right.  Taking into account every way that any given line of code can fail can be overwhelming to those not accustomed to it.  Plus, since each instruction in your code runs in series like a monstrous line of falling dominoes, the slightest error in your logic can have far-reaching repercussions.

The only way to make sure that your software is stable, that it does the job that it was meant to do, is to accept and embrace its imperfection.  With every line of code you write, you need to ask yourself questions.  How do you expect the instruction to run?  What will it do if it fails?  If you give it a weird input value that it wasn’t expecting?  If it throws an exception that interrupts the normal execution thread?  If you lose connection to your external resources?  Can you recover from a failure and keep going?  How do you alert someone that a failure has occurred so that it can be tracked down later?

A lot of this comes back to one of the points that I made last week, about respecting your interfaces.  Codifying all of the different pre-conditions and post-conditions of a code module will take you a long way towards understanding all of the different ways that it can fail, which should then be codified themselves.  Breaking your code down into small, reusable chunks is a big help with this, as there’s a lot less that you need to understand at once in order to cement that interface.  A program is far easier to write and maintain when it’s made up entirely of small black boxes, whose ins, outs, and faults are all completely understood and documented, held together by thin and simple glue.

And the thrilling conclusion…

Next week, barring a stroke of genius, will finish up this little series with the last two pearls of wisdom I have to share on the matter.  I’ve been light on technical detail, I know, but one of my goals is to keep this accessible to people just starting out.  Good habits are easier to learn at the start, before you have to unlearn all the bad habits you inevitably pick up.  Got any bad coding habits of your own that you’ve managed to break?  Tell me about them!

For those of you who don’t know, I’m a software engineer by trade.  I make my living serving as a mediator between man and machine, translating human thought and intent into little ones and zeroes.  I’ve been doing it for over a decade now (gah, now I feel old); I’ve seen a lot of source code and used a number of different technologies.  There are plenty of people out there who are more experienced than I am and have a wider breadth of knowledge, sure, but I’ve been around the block enough times to recognize some of the patterns and practices that separate good code from cryptic, rotting spaghetti.  Describing even just the ones I recognize could fill whole books, though, and is far more than can be meaningfully discussed in a single blog post.  But even without delving into too much detail, there are still several high-level concepts that, in my opinion, one must embrace to write truly effective, reliable, and maintainable software.

Be Explicit

One of the biggest hurdles that new software engineers have to overcome is learning how to think like a machine.  As human beings, we have the fantastic ability to overlook and ignore detail.  We don’t have to think about how to make that peanut butter and jelly sandwich that we’re craving, we just get the stuff and make it.  Computers don’t have that luxury.  A computer has to be told every tiny little step, from finding the fridge to identifying the desired ingredients to laying out the workspace, and on and on and on.  If you’re lucky, you’ve at least managed to find a third party library that will handle the actual physical movements involved, otherwise now you’re stuck trying to teach the computer how to walk, too.

The devil is in the details, and software is all details.  Assumptions lead to mistakes, and those mistakes can wait a long time before they rear their heads.  Hell, just today I fell victim to the assumptions of the coder who came before me.  He thought that it would be a good idea to fetch a customer record directly from the ID entered on his form, not realizing that it can take an ID or an email address.  Finding and fixing that error cost me almost an hour.  Even if you can get your program to work, making assumptions when writing code just makes it that much harder for the next person to come along and figure out what you were doing in order to fix that one-in-a-million bug.  If you’re really unlucky, that person will be you in five years.

Respect Your Interfaces

Any piece of software of non-trivial complexity gets big.  It just follows from the previous point: having to spell out all those tiny little details takes a lot of bits.  The only real way to handle this is to break up your code into smaller chunks, the most common type being called functions, which you then snap together like so many Legos.  While this is great for simplifying your code, by virtue of breaking up large tasks into smaller and more manageable ones, it can turn your code into a bunch of inscrutable black boxes if your functions don’t define strict, detailed interfaces.

Interfaces are very much like contracts; in fact, many programmers like myself call them such.  When you write a function, you’re making a promise.  You’re promising to everyone that will ever call it that your function will take certain inputs and yield certain outputs.  But like real legal contracts, unless you nail down every last little detail, you’re going to end up with behavior that you didn’t expect.  Some languages let you write better interfaces than others.  A well defined contract will specify exactly what types of data are coming and going, ideally custom data types that represent exactly what you want (e.g. a geographic longitude) rather than simpler primitive types (e.g. an integer); this lets you know exactly what you’re dealing with, what it means, and what you can do with it.  Worse languages just give you the name of the variable but don’t bother to detail anything regarding its type, assuming that you just know.  While such languages can be easier and faster to work with in the short term, those kinds of assumptions are breeding ground for errors and will come back to bite you in the ass, repeatedly.  The really bad languages?  You don’t even get a name.

Next Time, Gadget…

Well, that ended up being a lot more words than I was expecting.  There are a few other principles that I think are critical to developing good software, but I think I’m going to leave those for another day.  It can be a real series!  How about the rest of you code monkeys out there?  Share some of your own words of wisdom in the comments.