You don’t write software for you, you write it for Alex
TL:DR
Alex is the well meaning, enthusiastic, idiot, who will be inheriting your code 2 years from now.
Well meaning — They are not malicious, they are trying to ‘improve’ your code.
Enthusiastic — They are not shy about making large changes to the codebase.
Idiot — They do not have any of the context that you had when you wrote the code, they do not have the same skills / experience.
Idiot does not mean stupid, it means they do not have the context that you currently have.
You need to make everything you write “Alex proof” by making it excruciatingly obvious what it is trying to do.
You need to set Alex up for success, they depend on you making good decisions early on to set up standards / patterns to allow them to be productive with the code you have written.
There is a good chance you will be Alex.
Who is Alex?
So, Alex.
Alex is the well meaning, enthusiastic, idiot, who will be inheriting your code 2 years from now. They are the reason you need to write you code in as clear a way as possible.
Those 3 attributes are important parts of Alex’s character and need to be expanded in a bit more detail.
Well-meaning — Alex is not a malicious actor in the codebase. They are actively trying to “improve” your code. They want to add new libraries / frameworks, update versions, use best practices, follow standards.
Enthusiastic — Alex is not shy about making large scale changes to the software, they will happily refactor your code, update the architecture, rip out things that they think don’t make sense. Having code that you think “nobody will ever touch this” won’t work here, everything is on the table for modification.
Idiot — Alex has none of the context that you have, they weren’t in any of the meetings you were in when planning the code. They don’t have an innate knowledge of the domain or the ways in which different concepts within the domain interact.
You might be thinking that idiot in this situation means that Alex is either stupid or not competent. It does not. Idiot, here, refers to the lack of context that Alex has when considering your code. In all other aspects, Alex is a smart, functioning, human being.
Alex is the person who will be picking up the code you have written and trying to implement some new feature, or refactor it, or fix some bugs. Whatever the business is interested in that day.
There is something else you should know about the identity of Alex…
I’m Alex, you’re Alex, they’re Alex, we’re all Alex
Alex can be anybody.
Alex is a hypothetical future developer, they aren’t real and yet they are very, very real. Someone is going to be reading your code, trying to understand it, modify it, at some point in the future, another, very real, human being is going to be Alex.
Alex is you
Often, Alex will be you, coming back to the same codebase a few years later to fix some bug that has been discovered. Alex will be an older you, more experienced, less able to remember why exactly you did that thing where labels are passed around instead of IDs…
This is a classic rite of gaining experience as an engineer, coming back to your old code and wondering why on earth you did it that way, you were so naive, there were so many better ways you could have done it. This is fine and normal, it shows growth.
However, you now know, that you will be coming back to look at your code, with the critical eye of someone more experienced, and the searing kind of judgement that one only reserves for oneself. That’s a thing you know, right now, today, so, help your future self out, make sure your code is “Alex proof”.
We are Alex
You will not always be Alex, if you work on any kind of codebase that is shared with more more than one person, there will be other people inheriting your code.
They might be the bright-eyed new engineer, short on deep technical knowledge but long on enthusiasm to show they can do the job. They are not going to know what best practice is, you might have assumed that someone reading your code is going to know and understand architecture. Alex might not, they might just try to put everything in one massive file, they are especially likely to do this if there are pre-existing examples in the codebase of this behaviour.
Alex might also be a contractor, being paid a very hefty daily salary and for that salary the business wants to see results. They might not have any great affinity for the codebase, they have a job to do and are going to look for the easiest way to do it.
Alex could be the senior engineer, experienced, with the time to use that experience. They are less likely to make mistakes, going to take the time to learn the codebase and domain.
They are still an idiot.
They won’t know the story behind why a particular piece of logic behaves the way it does. They won’t have the knowledge that you gained after long conversations with the product manager / users / stakeholders. All Alex has is the codebase.
The codebase should not just contain the instructions for the computer to run it, it needs to contain the instructions for the humans to work with it.
Excruciatingly obvious
Code should be more than painfully obvious, it should be excruciatingly obvious.
The reason a code is doing the thing it is doing should be so obvious that you’re are going to wince at how stupid you are going to look as the author of code that is so over the top in explaining what every part is doing and why.
To you, as you write it, it’ll look ridiculous, it’ll seem unnecessarily verbose, but to Alex, it’ll be a gift, sent from the past.
The only thing that Alex is working with is the code, if there are parts that are not explained, or using some framework / pattern that is particularly niche, Alex is going to make so many mistakes. They are going to make wide changes to the system, misunderstand some assumptions and introduce all kinds of interesting bugs or anti-patterns.
Mistakes
The kind of mistakes that Alex will make are not just the obvious ones like bugs. They might also include things like:
- Introducing a new framework for one small section of the codebase without converting the rest, leaving a two-tier codebase where you the next engineer needs to understand both
- Putting lots of loosely related related logic in the same class, over time these classes grow and ultimately become very hard to refactor. These are things usually named something like FooUtils or FooService.
- Leaking details of external systems throughout the codebase rather than keeping APIs clean and hiding details in an adapter layer. A common example here is details of HTTP (URLs, HTTP methods, status codes) finding their way into the business domain or even the database layer.
These kind of mistakes aren’t bugs themselves, but over time, these are the kind of mistakes that make bugs more likely. They are also the kind of mistakes that make iteration speed of a codebase slower, which is a killer for businesses.
Compound mistakes
The mistakes Alex will make don’t stop with Alex, they compound, the next Alex is picking up a codebase that is less easy to understand and is more likely to make more mistakes, and the next next Alex, and on and on…
You need to make your code “Alex proof” as early as possible.
You need to make sure that the architecture and patterns scream at the engineer from the codebase.
You need to make the ‘right’ thing to do, the easy thing to do.
There are a lot of different ways to do things, but if the codebase has very clearly laid out it’s opinion on the way something should be done, then Alex’s job is a lot simpler. They are not thinking about how to structure an endpoint, what package structure to use, how to name classes, all of these kind of things should exist from the beginning and be consistent so that Alex can pick up the code and be productive with it.
Set Alex up for success
We write software to be read by other humans, not to be read by computers, I cover this in my story on the Golden Rule of Software Engineering.
Alex will be the other human that is reading the software you write. Alex is will be a real human being, they are probably going to be different from you, different experiences, different ways of looking at things. Importantly, Alex is coming at the code you write from a cold opening, they will need help getting up to speed.
Any software that you write needs to be written in a way that sets Alex up for success. You need to lower the bar to understand the codebase. Not just because you are setting up future contributors for success, but also because there is a good chance you’ll be setting yourself up for success.
It can take a bit extra effort to make an extra sweep over the code you’ve written to make it clearer. However, the amount of time you spend making the code easier for Alex will save them a much larger amount of time.
Make your code easier to understand.
Be kind to Alex.
Summary
Alex is the well meaning, enthusiastic, idiot, engineer that will be inheriting your code 2 years from now.
You need to make the code you write “Alex proof”.
You do this by making the code excruciatingly obvious, the architecture, patterns, concepts and context should scream at the reader from the codebase.
Help Alex by reducing the amount of brain space required to be productive in the codebase.
Overall, you need to make sure that your code is setting Alex up for success.
About the author
Hi, I’m Doogal, I’m a Tech Lead that has spent a bunch of years learning software engineering from several very talented people. When I started mentoring engineers I found there was a lot of knowledge that I was taking for granted that I think should be passed on. These stories are my way of trying to pay it forward.
