Why Context Erosion is a Problem

As an iOS engineer I have spent my professional life reading, producing, and sifting through a lot of code. I’ve been tasked with finding the tiniest details that can make or break a product experience and fixing old issues with new solutions. But recently I’ve noticed a pattern in the problems I’ve faced—context changes everything. 

On the most recent project I worked on, I was building for a large-scale iOS platform with about 120,000 lines of code, made up of 20 frameworks, and has seen over 80 different developers work on it. A project at such scale will inevitably have bugs and require on-the-spot quick fixes. The problem is that once a phase of the project is handed over to someone else, the nuanced understanding of a person’s decision making is lost. And then lost even more when it’s handed over again in the future. 

This loss is something my team has come to call context erosion. It’s a problem that’s easiest understood if we forget about code for a moment.

The Walter White Problem

This year for Halloween, I decided to dress up as Walter White from the TV show, Breaking Bad. I woke up early and my partner used makeup to give me a black eye and put some bruises on my face—as well as adding a “bloodied” bandage to my nose. When my kids woke up and saw me they were scared and worried. They didn’t know why someone had beaten me up! I tried to explain to them that it’s my Halloween costume. But my kids didn’t know the character and were visibly upset that I’d been hurt. 

The reality was that they only saw the end result, they didn’t have the context of why I looked the way I did. They’d never seen the show, so it was only natural that they would assume that I was hurt. 

And that’s what context erosion is: It’s when the end result moves further and further away from the original “why” of why something is the way it is, forcing you to risk making a critical mistake or spend time trying to find the root of the original problem. 

For my kids this meant I had to to assure them that I wasn’t hurt and I was doing an impression—a simple, but teary solve.

But for us engineers, context erosion can be a massive drain on resources, morale, and quality of work. 

It’s something I’ve seen first hand.

Back to Coding

A teammate of mine on a recent project was telling me about how the payment flow in the app has a problem because it uses an SFSafariViewController to let the user pay via a website. But, the SFSafarViewController also allows the user to bounce out to the Safari app by tapping on the Safari icon in the tab bar. And if the user does this, the payment doesn’t work. 

My colleague also told me that the app used to use a WKWebView instead but at some point they swapped it out for the SFSafariViewController. So I asked why? His answer: I don’t know. The Git history didn’t say why, and neither did the ticket. And unfortunately, the person who did the swap no longer worked at our client’s company. 

The context around this SFSafariViewController decision had completely eroded. 
My coworker ended up wasting a lot of time going back to the WKWebView trying to figure out why it was problematic. He ended up keeping it, but he wonders if there’s something he overlooked that might break the app.

Solving for Context Erosion

Put context into the tickets – The ticket is a great place to explain the context and reasoning behind the work to be done. It also provides the opportunity to link to other contextual artifacts like designs, other tickets, etc. Not only will this provide foundational context, it also helps the developer do their work.

Leverage source control – Source control is fantastic at recording code changes. Why not let it record context. Leave explanations in your code, commit descriptions, PRs, and code review comments.

Go beyond just replying to code review questions – If someone asks a question while reviewing code, don’t just reply to the comment, because in the future someone else reading that code will have to dig up the review and go through the comments to find that piece of important context. Add that context to the code itself or to the commit description.

Disable squashing and fast forward pull request merges – Squashing diffs and commit messages/descriptions are a bit like downscaling 4K video to 480p—information is lost and finding specific information becomes harder. Fast forward (or rebased) merges for pull requests isn’t as good as forcing a merge commit because the merge commit will automatically get some helpful context—the PR number and a link to it.

I’ve found context erosion to be one of the least talked about challenges in the complex world of software development. Just by giving it a name, I and the team at Connected have begun to find solutions to the problem. As for my life at home, the next time I dress up for Halloween, I’ll be sure to show my kids an episode of Breaking Bad before they see my costume—although come to think of it it’s probably best not to give a 5 and 6 year old context about methamphetamine manufacturing. For devs though, it’s crucial to remember that context is key.