Empathetic Code
We humans often take mental shortcuts. We assume everyone thinks like us, and often underplay how our ideas of what is easy or hard or good or bad are shaped by our experiences and skills. We will often refactor or write code so that is it easier for us to read. We say we made it more readable. But readable for who?
There is no such thing as readable code nor unreadable code. At least without either explicit or implicit reference to an audience. Readability/Understandability of code is not as a property of the code itself, but a property of both reader and code.
An experienced OO programmer who is unfamiliar with functional programming will struggle to make sense of a new codebase using functional style, and similarly a functional programmer in an OO codebase. From the infinite OO vs FP flamewars online it’s clear to me that one is not better than the other, but familiarity wins every time.
But this isn’t just about patterns and styles. A new domain can be equally challenging. When I first moved into the world of supply chain software it took me a good 6 months before I had a good grasp of the wider context within which we were working. This context was vital for understanding the code. A domain expert can handle acronyms and complex processes even when the details are mildly obscured by messy code because they have scaffolding to hang their understanding from.
Similarly, developers who have worked on the same codebase for many years develop a deep and complex mental model of how that codebase works. They have a 6th sense for how to debug and triage issues and the complex multi-step deployment process is an old friend. Over the years they have accumulated all sorts of custom scripts and backdoor methods which make them incredibly efficient when they want to perform routine tasks like finding logs or debugging in production.
Developers new to the codebase often get frustrated by the experienced developers resistance to changes that would improve their ability to work in the new codebase, while the experienced developers get frustrated by what they perceive to be unnecessary change to a system that works.
Or the opposite can happen and developers familair with the system can make significant changes to architecture, implementation or workflows because they have the spare mental capacity to handle it, without thinking about the new joiners who all ready feel like they are juggling more than they can handle and just don’t have the capacity to deal with any more newness.
To compound these issues, emotions can come into play. We can all struggle to depersonalise technical disagreements. We often view the other person as an adversary who wants to do us harm rather than starting from the assumption that they just wants to see the project succeed.
Walk a mile in their shoes
It can be difficult to understand what is going on in other people’s head. A trick I often play is to think of a time where I have behaved in the same way as the person I am seeking to understand.
Try to remember that readability is a relationship between the code and the reader. Just like writing an essay, we should ask ourselves, who is the the audience we are writing for? What do they know? What am I trying to convey to them?
Putting yourself in someone else’s shoes like this is called cognitive empathy and is a vital skill in software that is often overlooked. It requires us to unpack our own thought processes, why do we prefer x to y and then try to understand how a different set of experiences may change our perspective.
Being more empathetic when writing software
When making a change to make code, ask yourself is it really an improvement? Be conscious when making changes to how software is written that there is a value to conforming to the wider context of the project and experiences of the team.
You may think that English is the best language in the world, but if you move to Paris and insist on only speaking English, it could be somewhat suboptimal (even if you shout really loudly and slowly).
Be clear what problem you are trying to solve and how you will measure it. By doing this you help others to have empathy with you. They understand why you are proposing these changes and the challenges you face. This helps bring them along with you on the journey and allows them to become a part of the solution. It also gives them the opportunity to raise issues with your solution that might impact them.
By measuring the impact of the changes you are making, experiments have a clear success or failure. In the case of failure you can rollback the changes rather than leaving lots of half finished experiments littering the codebase.
Beware of change induced overhead
Change is hard, people feel uncomfortable while adopting new ideas.
Even once we have agreed to proceed with a change, that change causes everybody extra cognitive load and stress. Incomplete changes lead to confusion.
To reduce burden try to finish what you start or back changes out when you decide an experiment has been proved ineffective. Frankenstein codebases tend to combine the worst of all the patterns they include.
Limit changes in progress — let new processes and patterns embed themselves in the org before introducing more. Change is hard, people feel uncomfortable while adopting new ideas.
By being able to demonstrate concrete improvements early on, you will start to win people around to your cause. Long lasting change can only be had by bringing people along for the ride. You know you are winning the war when the old guard start to take up the fight on your behalf.
Introduce change slowly and ideally in an easily reversible and safe environment first. If it doesn’t give the results you expected, don’t be afraid to back away from the idea having learnt something new.
Put in the work
Take the time to understand the system that you want to change. What problem is it solving? How does it work? Why was it written that way? What works well because it was built that way? What is the history of the project?
Start by assuming smart people worked hard over many years to get the system to the point it is today. Nobody sets out to confuse those that come after them. This will win you the respect of those who you need to bring along.
After you have put in the effort you might find that your relationship with the code has changed, maybe it doesn’t need to all be rewritten and you can focus on working together as a team to address issues with shared understanding and without dogma.
If you dont understand, have a conversation!
If someone is dead set against an idea you think is a no brainer, speak to them about it. Maybe you can learn something. Or maybe you can understand what is worrying them and find a way to get the best of both worlds. Human interaction can’t be codified, but a curious mind is rarely harmful, and most people like to feel heard.
It’s not just code
In this post I have focussed on how cognitive empathy can help you when writing code. But writing code is still only a tiny piece of the puzzle that is building a great solution to a problem.
It turns out empathy is widely applicable throughout this process, not just when cutting code.
When creating pull requests structuring your commits to tell a story of the change you are making that is relevant to the reviewers including meaningful commit messages and a description that takes into account their context can be extremely valuable.
When writing documentation put the user needs at the heart of the process. For example take a look at the Divio system and figure out which category is most appropriate for the use case at hand.
For more information I would highly recommend reading more about empathy driven development as well as watching One weird trick to becoming a better software developer 😉.
Practice, Practice, Practice
Cognitive empathy is a skill, at first you will probably find it very challenging, but with time and practice you will improve, and eventually it will become second nature. Unfortunately empathy is widely lacking in this industry, but by modelling empathy you can start to be part of the solution; your colleagues and your career will all benefit from your new super power.