Sympathy for the Reader

There’s an old aphorism about writing good code:

Code as if the next guy to maintain your code is a homicidal maniac who knows where you live.

Very humorous, worth a good chuckle and maybe a knowing nod.  But is this a helpful model for motivating programmers?  I doubt it.

Writing good code won’t come from a call to action based on fear of the next guy.  It might come from a sense of empathy.  Today I want to lay out a more concrete version of the above quote that I think might be more likely to change your behavior.

Nobody Reads the Code Just Because

At the beginning of a project, it’s reasonable to expect that someone, or even everyone senior, know everything that’s going on in the code.  As features accumulate, as more hands become involved, as coordination becomes something you have to actively work for, this begins to fade.  Pretty soon it’s just the leads.  It’s not long before people become unfamiliar with bits of the code.   Now you start witnessing conversations where a lead says “This is how the code works,” and someone gets an uncomfortable look and says, “Well, no, that’s not how it works anymore…”.

People Read the Code Because There’s a Problem

The backlog is full and there are deadlines to make.  Nobody is spelunking in parts of the application code for their own amusement, and only rarely for their own edification.  Most of the time, if they’re in a bit of the code they are there for a reason: There’s a problem and they are hunting for it.  We don’t just have problems when we’re picking bugs off the backlog.  We have problems every time the code doesn’t do what we expected the first time we try something.  In fact it’s quite likely that most of your week is looking into problems.

Faced with a problem, the person may have only a rough idea of which part of the code is involved in the problem, so they may have hundreds or thousands of lines to go through.  They are searching for something that ‘looks funny’, because when something went wrong, it’s because something unexpected happened, so let’s look for unexpected behaviors in the code.

Debugging is a process of eliminating false positives until you arrive at the root cause. This is the biggest reason that Code Smells are a big deal, and not just some bit of aesthetic frippery or hokey religion.  Every bit of smelly code they look at becomes suspect.  They have to eliminate it as the cause.

If an important data flow is full of ‘clever’ code and old tech debt, it has the potential to ‘nerd jack’ every developer who comes near it, every time there’s a problem.  But as the author of this insult you probably won’t ever hear about it. By the time the developer hunts down the root cause, they’re so tired and so relieved the pain is over, that they just fix the problem, claim victory, and go off somewhere to recuperate.  In my case I will throw down a ‘git blame’ and watch out for patterns.  If I suddenly become bristly toward you for no reason you know of, this is probably why; your code has caused me (or someone I’ve been helping) enough grief that I find it difficult to trust you now.

Why Write Clean Code? As a Kindness

With this in mind, I’d like to offer a different guideline.

Code as if the next person who reads it is having a bad day.

If they aren’t having a bad day already, it might turn bad once they look at your code.

In another post I’ll go over some of the Code Smells that I believe contribute to this class of problem.





About innerjason

Software Developer
This entry was posted in Development, Uncategorized. Bookmark the permalink.