Legacy Code Testing and Requirements

One of the first traps you run into as a developer working on Legacy Code is to ask for the original requirements. It seems logical. Let’s figure out what the original designers of the machine intended. However for legacy code, that is a rabbit hole that will lead you in the wrong direction.

The Problem

In architecture, there is the idea of as-designed versus as-built documents. The architect designs a building and creates a set of documents. These are as-designed documents. However, during construction, things deviate a little bit. Maybe the exact material the architect specified wasn’t available or was too expensive, or the builder discovered an easier way to route a pipe, so the construction crew made a substitution. That gets documented in the as-built documentation. When you go to do later remodeling, you want to look at the as-built documents, not the original as-designed documents.

The problem with looking at the original design documents is that they don’t accurately describe what originally was built and even less what exists now. Any software that has existed for any amount of time has been modified. Bugs have been fixed. Features added. So the software itself has changed. The original requirements may have also changed. They may no longer be applicable. Either way, the original requirements are obsolete.

A Real World Example

A few years ago I got called in to update a machine. It was a machine for manipulating soil samples, so it was exposed to water and dirt. That caused a lot of mechanical failures, so they had redesigned the mechanical side of it to make things more sealed. That required some small changes to the software, mostly just to the driver level. I asked for the original requirements. The machine was 10 years old, so they didn’t have any.

There were several people involved: the manager, the tech lead, the mechanical engineer and the technician who ran the machine. None of them could agree on what they thought the machine was supposed to do, and none of them agreed with what I thought was supposed to happen based on looking at the source code. So we literally sat there with a stopwatch and timed each step. The lesson was that whatever anyone thought the machine was supposed to do, the important thing to preserve was what the machine actually did.

A Better Way

The key to working with legacy code is to be behaviour preserving, regardless of what the original requirements were. Whatever it does now, someone is relying on that. So our goal needs to be preserving the current behaviour. How do we do that? Well, we use something called a golden snapshot or approval testing. We basically capture the current output and save that as the standard. Then we write tests that compare the current output to the standard. That way we know if something we change affects the output and we are able to preserve the original behaviour. In the case of the soil sample tester, the ultimate test was to take a single sample, split it in half and run half through the old tester and half through the new tester and compare the results.

Help!

If you are looking for help legacy project, we’d be glad to help. Let’s schedule a call to talk about it.