On Modifying Software You Didn't Build

Over the past two decades, I have stepped into hundreds of projects that had a foundation established by the software engineers before me. The process is similar to reading the recipe of a soup or a curry you just tasted: through sight, smell, and taste, you already know some of the ingredients, but the exact recipe is still a surprise.

Before you peek behind the curtains of a piece of software, you envision how it may work. But it never completely matches your imagination. There are always bits that confuse you. "Why would they have built it like this?" In my experience, engineers have two strategies to avoid answering that question:

• conserving, assuming there is a good reason, and
• destroying, assuming there isn't a good reason.

Those who wield the first strategy are the tiptoe-ers. Tiptoe-ers endanger the evolution of the project. By not questioning existing structures, they fossilise suboptimal decisions made in the past – sometimes years ago by predecessors who have changed jobs twice since. They never become true project experts because they miss out on the valuable insights gained from foundational scrutiny. Progress grows increasingly costly and risky. Eventually the project grinds to a halt and needs to be rescued by the antagonists: the flamethrowers.

Unfortunately, the flamethrowers have their own unique way of ruining the project with their good intentions. There is valuable knowledge and experience encapsulated within the smelly lumps of code they burn to ashes. The flamethrowers repeat old mistakes, reintroduce previously fixed bugs, and relearn lessons already learned. If left unchecked, they will put the project in a perpetual state of one refactor after the other (but this one is going to solve all of the problems, just one more and everything will fall into place!)

In martial arts, the prevalent culture is one of following and imitating your teacher. Questions are welcomed; argumentative exchanges between a teacher and a student are considered inappropriate. You "steal" from your teacher: you try to mimic them as faithfully as possible.

Somewhat hidden within that culture is a shared understanding that that is not sustainable. If every teacher is but an imperfect copy of their teacher, the art depreciates with each new generation until it is like a photo of a printout of a screenshot of a low quality JPG. After years of dutiful imitation, students are lightly encouraged to turn their studies inwards. They start to explore new terrain from a position of deep understanding. Rather than a copy of their teacher, they become the original version of themselves.

I find a similar approach to software engineering is crucial to success. When you enter an unfamiliar project, you first understand, then adapt, and finally innovate. Organisations often unintentionally disincentivise a journey through the three stages, and most engineers are either tiptoe-ers or flamethrowers at heart. There is an important role for mentors in guiding engineers through the process (psychological safety is a prerequisite!) Absorbing the past can be tedious and thankless, but ultimately it helps your project thrive.