4 min readJust now
–
As software engineers, we often ask ourselves: how do we write scalable code? But more often than not, what we really mean is: how can we write code that leads to scalable, performant systems? This post is **not **about answering that question. For some thoughts on that topic, check out my other post. Instead, we’ll take a brief look at a different, more literal interpretation of this question. How do we write code that is itself scalable, and why is that important? Scalable code lasts the test of time and changing hands of hundreds or even thousands of people with evolving requirements. I’ve been fortunate to have the experience that started with a handful of engineers and has grown to hun…
4 min readJust now
–
As software engineers, we often ask ourselves: how do we write scalable code? But more often than not, what we really mean is: how can we write code that leads to scalable, performant systems? This post is **not **about answering that question. For some thoughts on that topic, check out my other post. Instead, we’ll take a brief look at a different, more literal interpretation of this question. How do we write code that is itself scalable, and why is that important? Scalable code lasts the test of time and changing hands of hundreds or even thousands of people with evolving requirements. I’ve been fortunate to have the experience that started with a handful of engineers and has grown to hundreds today. I’ve been able to see firsthand the necessity of scalable code and how tricky things can become when it is not. We’ll explore why this matters and why we need to broaden our perspective on software engineering to include time, people, and risk. We’ll also have some fun little AI-generated ASCII diagrams to help visualize the points.
If you want a great resource on more of the how of this topic, I highly recommend checking out Dave Cheney’s tips on writing great Go code: https://dave.cheney.net/practical-go. Although written for Go, the principles can be taken to any language.
Growing Audiences
No one is going to understand the code you write better than yourself, especially when it’s fresh. But unless you are working entirely alone or on a personal side project, your code’s audience will be much larger than you think. I like to think of the audience or reader of your code as: your present and future self, your coworkers today and in the future, other systems and machines, and now AI. All of these readers need to be able to understand and reason about your code. The easier it is for them to understand, the more productive the team will be, and the fewer bugs will occur due to incorrect assumptions or misunderstandings. If you are more visual, check out this ASCII diagram:
AUDIENCES ┌─────────────────┐ │ YOUR CODE │ └─────────┬───────┘ │ ┌─────────┼─────────┐ │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ HUMANS │ │ FUTURE │ │ AI │ │ │ │ YOU │ │ │ │ • Teams │ │ │ │ • LLMs │ │ • Interns│ │ • 6mo │ │ • Tools │ │ • Reviews│ │ • 2yr │ │ • Analysis│ └─────────┘ └─────────┘ └─────────┘ │ │ │ ▼ ▼ ▼ Need: Need: Need: Clarity Context Structure Names Comments Patterns Flow History Consistency
Exponential Risk & Complexity
In a growing organization, the complexity and associated risks grow exponentially. This is due to the number of times a piece of code changes hands multiplied over time. Check out the ASCII diagram below for a more visual interpretation of this point:
Exponential Risk/Complexity growth:Time → T0 T1 T2 T3 ┌───┐ ┌─────────┐ ┌───────────────┐ ┌─────────────────────┐ │ 1 │ │ 4 │ │ 16 │ │ 64+ │ └───┘ └─────────┘ └───────────────┘ └─────────────────────┘T0: Initial Change ┌─────────────┐ │ Code Change │ ← Single developer, single file └─────────────┘T1: First Usage Tree (4 people) ┌─────────────┐ │ Code Change │ └──────┬──────┘ │ ┌──────┴──────┐ │ │ Dev A Dev B │ │ ┌──▼──┐ ┌──▼──┐ │Copy │ │Adapt│ ← Different interpretations └─────┘ └─────┘T2: Ripple Effect (16+ people) ┌─────────────┐ │ Code Change │ └──────┬──────┘ │ ┌──────┴──────┐ │ ASSUMPTIONS │ ← Interface assumptions solidify └──────┬──────┘ │ ┌──────┼──────┼──────┼──────┐ │ │ │ │ │ TeamA TeamB TeamC TeamD Vendor │ │ │ │ │ ┌─▼─┐ ┌─▼─┐ ┌─▼─┐ ┌─▼─┐ ┌─▼─┐ │ ? │ │ ? │ │ ? │ │ ? │ │ ? │ ← Each creates their own interpretation └───┘ └───┘ └───┘ └───┘ └───┘ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ More More More More More Code Code Code Code CodeT3: BLAST RADIUS (64+ exponential growth) ┌─────────────────────────────────────────────────┐ │ 💥 EXPLOSION 💥 │ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │ │Prod │ │APIs │ │Libs │ │Docs │ │Tests│ │ │ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │ │ ▲ ▲ ▲ ▲ ▲ │ │ ┌──┴──┐ ┌──┴──┐ ┌──┴──┐ ┌──┴──┐ ┌──┴──┐ │ │ │ ? ? │ │ ? ? │ │ ? ? │ │ ? ? │ │ ? ? │ │ │ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │ │ │ │ 🔴 Bug becomes "Feature" (too late to fix) │ └─────────────────────────────────────────────────┘
Without scalable code, every new engineer multiplies the risk instead of distributing it.
Intern Rule
This is more of a “how” point, but I felt I should share it either way. A good rule of thumb I always try to keep in mind when writing code is what I like to call the “intern rule.” Essentially, all this means is that five years from now, when an intern reads your code, they should be able to understand it. You should never assume your code is “self-explanatory” and instead make sure it’s clear and very well documented. Like the other sections, here is your AI-generated ASCII diagram:
INTERN RULEYear 0: You Write It Year 5: Intern Inherits It┌─────────────────┐ ┌─────────────────────────┐│ │ │ ││ 🧠 = 100% │ → │ 🧠 = 5% ││ │ │ ││ • Full Context │ │ • No Context ││ • Your Patterns │ │ • Different Background ││ • Your Domain │ │ • Time Pressure ││ • Your Style │ │ • Learning Mode │└─────────────────┘ └─────────────────────────┘ │ │ ▼ ▼┌─────────────────┐ ┌─────────────────────────┐│ Can you write │ │ Can they understand, ││ code that │ │ modify, and extend ││ survives this │ ? │ your code without you? ││ transition? │ │ │└─────────────────┘ └─────────────────────────┘
Scalable code is far more than just worrying about performance. It’s about the longevity of your code. It’s code that survives people, time, and chaos. If your code is easy to understand and contribute to years from now, you can be confident you’ve written something that can truly scale.