Afterwood

As I write, the UK is going through political turmoil. The current Prime Minister (PM) has finally stepped down as leader of his party and so we’re in for a new PM in the coming months. Given the various shenanigans that have gone on over the last couple of years, it’s unlikely that history will look kindly on him, although some of the more recent changes in policy feels like it comes straight from Orwell’s 1984 so maybe we’ll never unearth the truth.

Much like the last two Prime Ministers, my own tenure is shorter than a normal employee because I’m a freelancer. One consequence of moving on frequently is that I get to reflect on the ‘legacy’ that I’m leaving behind for the team. Hopefully, unlike the last few PMs, my parting gifts are looked upon with more affection.

Outside the world of software development, the term ‘legacy’ has a far more positive meaning. It’s commonly used to convey some asset (money or property) that’s left as part of a will. By and large, receiving a legacy is A Good Thing and relished by the recipient. Conversely, in the world of software, it’s more generally used as a pejorative – inheriting a legacy codebase is more likely to be met with derision. If we take the extreme view put forward by Michael Feathers in his seminal book Working Effectively with Legacy Code, any code without tests is considered legacy code. Ergo, if you’re not practising TDD then you’re producing legacy code with every keypress until you pay off your debt by adding a test. When the PM said he “got Brexit done”, what I heard was “it’s code complete” – metaphorically, Brexit feels like a monster codebase with no tests.

Closely related and suffering a similar disparity in persona is the notion of inheritance. Finding out you have a long-lost, obscenely rich relative who you have inherited a massive estate from is the stuff which dreams are made of. In contrast, the thought of receiving a massive inheritance in a codebase fills one with dread. In typical programming fashion, the term is overloaded and not all inheritance is the work of the devil. Implementation Inheritance and deep class hierarchies are frowned upon due to the tight coupling they introduce, whereas Interface Inheritance is lauded for helping to loosen unnecessary coupling. In this work of fiction, the Open/Closed Principle is your overly literal uncle responsible for the quagmire of classes you find yourself wading through.

Refactoring parts of a codebase to make it both easier to understand and, more importantly, to change, is definitely the kind of the legacy we should all look to give and receive. George Orwell warned us in 1984 about people who had a habit of rewriting history, but I’d hope he would approve of its use to simplify code. Unlike in 1984, where any evidence of the past was eradicated, we have the wonders of version control to allow us to see how we got to the new state of affairs and why. Of course, version control tools come with their own problems and I’m sure Orwell would have plenty to say about squashed commits and rebasing.

For sure, improving the quality of the product’s production code is a rewarding legacy to pass on, but for me it’s also the easiest to justify and therefore also perhaps the least contentious. Personally, I look to improving those aspects of the software delivery process which are a little harder to instigate (often for political reasons) or less valued by others, but only because they may not realise what a difference it can eventually make.

Automated builds are far more common these days, but also being reliable and easy to reproduce locally is still a gap that frequently needs plugging. Before the rise of ‘DevOps’ as a more formal role, it was left to the developers to try and lash something together in and around their other duties. Much like testing, the ability to build and deploy the product took a back seat, and so taking on that ‘poisoned chalice’ feels like a challenge worth tackling. Making it easy to go from ‘works on my machine’ to ‘also works on the production machine’ really helps the flow. Sadly, the rise of so called ‘continuous integration’ products has meant that I now see ‘broken on the build server’ coupled with ‘can’t reproduce on my machine’ because the developers can no longer build, test, and deploy the product locally in the same way as the 3rd party product does it. Closing this gap always pays dividends in the end when it really matters.

Another task which rarely gets any TLC is documentation. The emphasis is traditionally on trying to make the code as readable as possible to make comments redundant. However, as Grady Booch likes to say, “the code is the truth, but it’s not the whole truth”. Matters of architecture and design, such as the rationale cannot be reflected in the code, only the outcome of the decisions. Similarly, even if you represent your platform as code, forcing someone to mentally derive the overall architecture by reading your Terraform scripts is not a pleasurable experience. Adding Architecture Decision Records and, say, a C4 model of the system goes a long way to helping newer team members understand the journey. Also having a wiki is a great start. What’s even better though is having some actual content in it. In general, I feel that developer documentation appears to be in the same state that developer tests were a decade ago – they were rarely found and, if they did exist, were poorly written. Giving a wiki some structure, content, and style so that it can be browsed as well as searched is probably my other preferred contribution that I hope makes my successors nod in approval.

Unlike the departing PM, I do not see my legacy as a medium for getting my ego massaged. My legacy is not some kind of monument to be revered; on the contrary, it’s more like the scaffolding that surrounds it enabling the team to work in safety. If it goes unnoticed that’s not a bad thing, if anything that’s an even bigger compliment as it means it’s not become a source of friction.

Chris Oldwood is a freelance programmer who started out as a bedroom coder in the 80s writing assembler on 8-bit micros. These days it’s enterprise grade technology from plush corporate offices the comfort of his breakfast bar. He has resumed commentating on the Godmanchester duck race but continues to be easily distracted.