Writing by Peter Hilton

Three causes of unmaintainable code

Why programmers are lazy and too clever for their own good - 20 August 2018 #code #maintenance

A factory - where real maintenance happens

unsplash-logoCrystal Kwok

Programmers will tell you that they have pride in their work. Some of us go as far as calling it a craft. The same programmers will tell you that other peoples’ code is unmaintainable and not to be trusted. Something is wrong here.

It turns out that conflicting software development goals can cause unmaintainable code. Programmers don’t object to maintainable code, but want other things more.

Programmer laziness

We’re lazy programmers. I’m talking about constructive laziness - the good kind of lazy, that leads a programmer to write code automate a task that they’re too ‘lazy’ to do manually. The catch is that programmers tend to enjoy coding enough to forget that the automation started as a means to an end, and end up spending more time on avoiding the task that they’re too lazy to do than the task would haven taken to do manually.

An hour’s coding often saves several minutes of boring repetitive work.

Programmers want work to be interesting and use constructive laziness to avoid boring work, rather than to save time. We assume we’ll save time. Sometimes we’re wrong. That’s why XKCD produced a handy chart: How long can you work on making a routine task more efficient before you’re spending more time than you save?

Programmer laziness causes unmaintainable code when it results in code that we don’t need. If you write code to avoid boredom, you probably shouldn’t try to maintain it as well.

Too clever for our own good

Faced with a routine manual task, constructive laziness encourages programmers to turn it into a coding task. Faced with a routine coding task, programmer hubris encourages ‘fixing’ the task to make it more interesting. Unfortunately, this tends to make the resulting code more ‘interesting’ too.

Irregular verbs:
I ‘come up with a clever workaround’
You ‘made some intriguing design choices’
They ‘create unmaintainable legacy code’

- David R. MacIver - @DRMacIver

Programmers want work to be interesting and tend to solve problems in ways that make the solution more fun to build at the cost of it being much less fun to maintain. We’re too clever for our own good.

Early adopter culture

Functional programmers are especially prone to being too clever. I don’t mean that functional programmers are more intelligent than other programmers. The problem is that functional programming is more fun than most of the business problems that professional programmers are paid to solve, which makes it distracting.

I love functional programming. It takes smart people who would otherwise be competing with me and turns them into unemployable crazies.

- William Morgan - @wm

Sometimes programmers get fixated on understanding and applying a new technology, instead of finishing their work. The good news is that functional programming, or some other new technology, may give you a higher quality result in less time. The bad news is that you’re likely to inflict the joy of learning and experimentation that you got from building the solution on everyone who maintains this solution, whatever their interests.

If you don't give software engineers explicit time for professional development, your production apps will become their test bed.

- Jason K Jackson - @jasonkjackson

This is the flaw in the age-old management fantasy that companies can replace formal training and slack (as in spare time) with ‘learning on the job’, a.k.a. no training. This causes unmaintainable code that was written as practice code, complete with the usual beginner mistakes.

Conflicting goals

While you (or your manager) may hope that programmers’ top priorities are to write maintainable software that you need, while avoiding unnecessary effort, programmers’ actual priorities are more like:

  1. Avoid boredom
  2. Avoid manual (i.e. non-coding) tasks
  3. Exercise technical mastery in coding

Writing maintainable code is, of course, way down the list. Still, it could worse: writing documentation is even lower.

For more help with the causes of unmaintainable code and how to address them, contact Peter Hilton for training in How to write maintainable code.

comments powered by Disqus