The code maintenance problem

Crystal Kwok

Among software developers, there are things that everyone’s talking about, few are actually doing, and even fewer need. Some architectures and frameworks come to mind. There are also aspects of software development that a lot of people are doing, but few people are talking about. Software maintenance is one of those things.

We don’t talk about software maintenance because we don’t want to face reality. It’s much easier to talk about the idealised perfect that we don’t actually have, because then we don’t have to admit to the problems we’re really facing, during long-term development. That’s a shame, because we’re ultimately be better off when we face up to the code maintenance problem.

The code maintenance naming problem

Naming’s hard, apparently, and the activity we call ‘software maintenance’ isn’t really maintenance. With machinery, it makes sense to separate the cost of buying or building something from the cost of keeping it running from year to year. Software isn’t like that though. There’s no useful distinction between the phases called ‘construction’ and ‘maintenance’, and the version 1.0 release is no more than an arbitrary date.

‘Software maintenance’ is really just software development. However, despite hardware maintenance being a bad metaphor, the alternatives are probably all worse, so lets talk about software maintenance anyway. After all, at least ‘maintenance’ captures the idea of work that keeps something working without making it any better. If you think that sounds pessimistic, then read on because it gets worse.

The code maintenance problem

When you first start on a piece of software, while there are only a few thousand lines of code, it seems like there aren’t any bugs or that they’re easy to fix if there are any. And when you want to add or change features, it feels easy and doesn’t seem to take very long. Then one day, you realise that there’s more code than you’ll ever read, all changes take too long, and development is constantly frustrating. The code maintenance problem is the extent to which making changes to software gets harder, slower and less reliable as the years go by.

When you break it down, it’s usually straightforward to identify where the problems lie. Bad naming gives you identifiers that might make sense historically, or to one specific person, but don’t help you understand what things are for. Code comments can be bad comments in at least seven different ways, ranging from being too few to being too many, as well as just plain wrong. Code can also fail to fit the intended architecture, or the team’s code style, especially since both are moving targets.

The code maintenance problem is that code lies. Code lies when naming, comments, architecture and code style mislead you. And the best thing to do with lies is to expose them.

Opening up about maintenance problems

Johannes Brodwall wrote about clean code shaming, and why we should embrace Compassionate Code instead. We’d certainly get along better if we were nicer to each other, and talked less about other people’s Clean Code and more about the code we have.

Even without doing it publicly, a development team can benefit from talking through their code’s maintenance problems. Even if this is only an occasional therapy session, it will be make you all feel a little better. That’s only the first step, though.

When a team talks about maintenance issues, they can discover which issues affect them the most, in practice. Team members know what the issues are, but probably aren’t used to talking about them.

The first set of issues a team identifies tend to focus on the code itself:

• bad naming, and other kinds of ambiguity
• bad comments
• big functions or classes
• code size and complexity
• code that isn’t written in a consistent style.

If you continue, you may discover broader issues and causes for code maintenance issues:

• code that’s hard to understand
• bad architecture
• insufficient or ineffective system documentation
• unpredicatable business priorities
• development that’s been influenced by too many different people
• code written by people who were being lazy or ‘clever’
• code with a long lifetime.

At this point, you’re still having a discussion, but if your team can talk about these kinds of things, then you might be ready to do something about the code maintenance problem.

Next steps

After discussing the code maintenance problem with the team, it’s time for three serious questions.

1. Why does maintainable code matter?
2. Whose problem is this?
3. Can we get help?

If you get the answers to the first two questions right, then the answer to the third is ‘yes’. When your team needs more than just a therapy session to help them deal with software maintenance, then contact Peter Hilton about training in How to write maintainable code.