Zen and the Art of Software Maintenance

FSS Zen Series

This article is one of our “zen series” software engineering articles, inspired by the Zen and the Art of Motorcycle Maintenance book.

Software maintenance is often an afterthought rather than an activity that is started when the first line of code is written; this article outlines some common software maintenance tasks and problems as well as tips to help you deliver software updates efficiently.

Software is not like a car; it doesn’t age, suffer from metal fatigue, wear or tear so surely no maintenance is needed? In some circumstances this is true, if you are developing software for a micro-controller in a household appliance you will ensure that the software is fit for purpose and tested to extremely high standards, because the consequence of not doing so is a product recall; which is every company directors nightmare, as both the costs and impact on brand popularity are massive. But the need to maintain software is omnipresent.

So what drives changes to software?

There are three main change drivers:

  1. Customer change requests. What the customer needs changes over time as does their ability to articulate what they need.

  2. Internal change requests. Your product exists in a competitive world, adding new features and updating the user interface are often essential tasks to keep up with the competition.

  3. Errors not identified prior to software release. Exhaustively testing software for non safety critical applications is often not cost effective, so bugs often exist in released code. When the pressure is on to release a product before a competitor does it is often accepted that quality may fall, with the assumption that the early-adopters won’t mind as long as they can easily get an update.

Change happens, so how do we prepare for it?

The first step is to understand some common software maintenance pitfalls. The second step is to make some small steps to prepare for change during software development.


Our experiences gained from assisting other companies to maintain their software has helped us to identify some common pitfalls:

  1. House of Cards. One small change in one part of the software leads to an unexpected result in another piece of software. There are two root causes to this: A) contradictory, poorly understood or tightly interwoven requirements. B) Terrible software design.

  2. Expert has moved on. Core parts of the software were written by a genius who has since moved on, the code is impregnable by anyone but the original author. The root cause of this is not the expert, but the expert’s manager!

  3. Can’t get started. The required change is understood, but it is impossible to understand what parts of the software are affected and how to make the change. There are two common causes for this: A) Poor software design. B) Poor software documentation.

Avoiding these pitfalls requires preparation for software maintenance during the original development, fortunately this preparation also helps with the initial development hence no net increase in development time should be noticed, the key tasks needed are:

  • Ensuring that you have the right team for the main development

  • Breaking the software down into layers and components with clear and distinct roles and responsibilities

  • Ensuring that high level architectural documentation is kept up to date and that the code package / module structure and names match the architecture documentation

  • Meaningful descriptions on all classes. Descriptions should start with a strong verb and expand upon what can be determined from the class name. A good class description enables a coder to see instantly how and where to use it appropriately.

  • Appropriate use of public, private, protected etc. Only expose what you need to.

  • Code style conventions. Every coder’s formatting should be consistent. Use a tool to enforce it. It makes reading other peoples code faster.

  • Ensure that you are using a good source control product. A good product is intuitive to use and places virtually no administrative burden on the coders. It should be easy to determine what was changed by who and when. Also it should be possible to easily view the code at different points in time, and to see the impact of change requests. There are several products out there, we use Perforce.

The preparation is in place, so how do we go about making changes?

The first step is to plan a release. Identify the changes that are to go into a planned release, aim to fit as many changes as practical into a release; this cuts the total number of releases and the total maintenance testing effort. Where possible ensure that all proposed changes in a particular functional area are implemented at once.

Ensure that an individual is responsible for the commercial decisions – what is covered by contract, warranty, good-will, company policy – and what is not!

For the planned release, verify the estimates for all of the planned changes. This requires the release manager to ensure that each of the required changes is properly understood and verified as a genuine need. A quick impact assessment should include identifying which parts of the software architecture will be affected.

Next identify how you are going to test the change and verify that there is no adverse affect on other functionality.

Allocate changes to “generalising specialists” try to ensure that people tend to work on the same functional areas, but that they have a working knowledge of the other functional areas as well. This makes it easier to shift people around when large tasks come in, it also makes for a communicative team and reduces the technical depth (and time spent) on the documentation of changes.

Tasks have been appropriately allocated, what else do I need to worry about?

Remember to ensure all changes are recorded against a change request in your configuration control tool, also we advocate maintaining a very brief amendment history in the file, with a link to the change request, the editor’s name and the change date.

Implementing changes efficiently is then down to the implementer. Spot reviews and third party testing are worth considering to help ensure that the quality is maintained.