A developer’s guide to avoiding the brambles

Software development is fraught with peril. For any development task, there are a million ways to do it wrong, and the one correct way is a small, narrow trail that winds quietly through the forest. It takes experience to know the path and to avoid the dangerous pitfalls along the way.

The following is a list of seven hard-won lessons from many trips into the dark forest. It is an opinionated look at what to do and what not do when navigating the treacherous trail of coding an application.  It’s far too easy to stray from the correct path, and these notions will help you stay on course and arrive safely at your destination with a minimum of snags, missteps, and misadventures.

Follow this advice and avoid the brambles.

Look both ways before crossing a one-way street

In the United Kingdom, they drive on the “wrong” side of the road. The Brits realize that visitors are not always aware of that, because on the crosswalks in London, there is text painted on the ground as you step off the curb that says “Look right.” Being American, my habit is to look left, so I appreciated the advice.

PxHere

But I couldn’t shake the habit, so I ended up looking both ways. 

And I realized that looking both ways was a good metaphor for coding: Protect against the impossible, because it just might happen. Code has a way of surprising you, and it definitely changes. Right now you might think there is no way that a given integer variable would be less than zero, but you have no idea what some crazed future developer might do. 

Go ahead and guard against the impossible, and you’ll never have to worry about it becoming possible.

Never make one thing do two things

Oh man, this is my personal pet peeve. There is no end to the trouble caused by having one thing do more than one thing. 

If you’re ever tempted to reuse a variable within a routine for something completely different, don’t do it. Just declare another variable. If you’re ever tempted to have a function do two things depending on a “flag” that you passed in as a parameter, write two different functions. If you have a switch statement that is going to pick from five different queries for a class to execute, write a class for each query and use a factory to produce the right class for the job.

It might take a bit more coding, but please know that the complexity created by giving one thing more than one responsibility (as Uncle Bob Martin would put it) is just begging for trouble down the road. 

Code against interfaces, not implementations

It’s all too easy—and all to common—to couple your code to specific implementations. You start out with an application that does all its logging to a text file. That works great in the early stages, but pretty soon your application is running on multiple machines, and now those text files are everywhere and hard to track and manage. You decide to log to a central database and soon realize that it is a very large job to change from writing to a text file to writing to a database.

If only you had coded your logging system against an interface. Then, when presented with the problem above, you could just write a new implementation of the logging interface, plug that in, and voilà! Problem solved!

It’s always easier to plug a new implementation into an interface than it is to pull out a deeply coupled implementation, the tentacles of which are entangled deeply within your application.

Fear not the explaining variable

Consider the following code.

if (
(user.age > 18 && user.hasValidID) &&
(!user.isBanned || user.hasAppealPending) &&
(currentDate >= event.start && currentDate 18 && user.hasValidID;

const isAllowedDespiteBanStatus =!user.isBanned || user.hasAppealPending;

const isEventOngoing = currentDate >= event.start && currentDate