This is the second in a series detailing what I consider “Thoughtful Code.” In the first one, I highlighted the high-level overview of what I consider “good” code, here I’m going to go (a lot) deeper into what this overarching framework means in its specific components. Well one of it’s components. Specifically, the context in which our code lives, and how that shapes our definition of code quality.
In this we’ll focus on why making sure that you situate any discussion about code quality and purpose in a more specific human context is so important. It is context that tells us a lot about how code works and what it means to the world. If we ignore this need to specify a context, we’re just wasting everyone’s time.
Why It’s Crucial to Acknowledge Context
So we’ll start with why “good” code discussions waste everyone’s time. Mostly, they waste time, because people are talking past each other. If one wants to get super-analytical, what’s happening is people never discuss or reach consensus on the terms of what makes the code in question “good” or “bad,” and instead are arguing about second-order outcomes of the code like how they feel when writing the code and what they expect the long-term maintenance of that code to be like.
To be clear: I think it is valuable and useful to talk about what future you expect for your code base. But I think you’ll only know success if you first explain and understand why you care and what you expect that to mean. Because new Fortran code is not what lights up Hacker News these days, but it is super useful in the relatively-narrow context of people working in a Fortran-first ecosystem where lots of old code exists.
What Context Makes Easier to Understand about “Good” Code
The reason we must define “context,” “goals,” or “values” for our code is that they make a huge difference. If your goal is to create an application that can run in almost any web hosting environment, and well, you’ll probably want to write it in PHP. But if you want the most performant embedding language in the world, you almost certainly shouldn’t be choosing PHP.
Instead, most of the time programmers discuss “quality” as if there exists some objective universe where PHP’s is “a bad language.” In doing that, we make it impossible to actually make any progress in the important work of more accurately understanding the world.
Part of my foundational belief in explaining “thoughtful” code is that so much time is wasted arguing that WordPress code is “bad.” And trust me, I’ve had these conversations, and felt the pain or WordPress code first hand. I get it. But I also think that people making those claims without putting them in WordPress’s context for its understanding of success (in its case, “that we run on any hosting account any end-user might ignorantly be on”), you simply are wasting your time and will go down so many conversational rabbit trails (AKA useless tangents) that you’ll wear yourself out.
Why People Disagree About Code Quality
The heart of disagreements about “code quality” is that people often conflate “that doesn’t work” with “I don’t like that.” And while I’m as guilty as anyone of doing that casually, I think it’s super important that I don’t do it most of the time in the context of evaluating if a given library or coding style is right.
This is a strange context to mention it, but I’ve always loved this quote from the 14th century Persian poet Rumi:
Out beyond ideas of wrongdoing and rightdoing,
there is a field. I’ll meet you there.
When the soul lies down in that grass,
the world is too full to talk about.
The poem goes on, and I encourage reading it. But this is part of my foundational beliefs about the world. And while I believe that things can be “too full to talk about” you still need to try. And when we set the contexts for a discussion we let it succeed.
Why “Bad” Software Often Succeeds
I’ve already mentioned WordPress, so this time I’ll explain why PHP and JavaScript succeed. By any popular or objective standards, they are two of the worst and wartiest languages in the programming ecosystem. But together they basically power the internet. Beyond these two silly and ugly little languages, the next most popular languages either in the web ecosyste are footnotes. (For objective data, Github lists PHP #4, Python and Java outrank it. JavaScript still wins by a mile. And I think many Python and Java deployments are non-web.)
These languages don’t succeed, aren’t being used to write video games, because of their beauty. Instead, it’s because their broader context “the web” has been growing like wildfire for nearly 30 years. First slowly, now almost entirely, the web has subsumed so many parts of human life that we barely even notice it as the sea we’re swimming in.
And JavaScript, as the sole language that every web browser supports, got an easy ubiquity. It’s flaws of design were of much less importance to its success than being nested in the most popular context of the last 100 years.
PHP’s story is a bit muddier, but largely the same. PHP had an early lead as “the language for writing server-side web applications” and never really lost it. The reasons for this are myriad (I go into many in “Why PHP?”), but the fact that PHP’s success there was a mere side-effect of its code-design decisions feels pretty indisputable to me.
Why There Isn’t Often One “Right” Answer
In nearly every part of life, we humans want certainty. We want people to know that we’re good, and we want to know for sure that someone we perceive as an enemy is “bad.” The philosophy and psychology that propels these truths is not my area of expertise. But I have copious evidence of the lived experience. Both feeling that pull for certainty from others, and myself wanting it.
The need for team-camaraderie and certainty is why so many people make the easy jokes about the warts of JavaScript and PHP, and skip out on the more interesting but complicated analysis of why they succeed and what that can tell us about the success of code projects.
Everyone who has looked at this deeply thinks that Haskell is one of the most intelligently-designed and useful languages. (If you’re partial to it, you can substitute “Erlang” in for “Haskell” in that sentence with no loss of meaning.) But the language isn’t taking over the world. Why? Because contexts don’t always match what academic purity points to as the “right” answer. In fact it almost never does.
How Context Interacts with More Specific Concerns About Code
Understanding the surrounding context “fewer people need to worry about processor-level performance of components because of Moore’s law” explains the huge rise of dynamic languages (like PHP and JavaScript, but also Lua, Python, and Ruby) over the last 25 years. Not seeing those trends because you were worried about “idiomatic C” is a classic case of the old expression “missing the forest for the trees.”
Even more than broad industry trends, though, being clear and specific about both contexts and their meanings is super helpful is getting clear about everything else about a project. There are contexts in which what “idiomatic PHP” wants does matter. But it’s not one in which you’re worrying about eking out the maximum possible performance from your very-slow, very-cheap integrated circuit.
It is only after we clearly know the context in which we’re operating that making choices like “Python or C#” can have any meaning whatsoever. Without knowing that we’re in a performance-sensitive scenario, or partnering with a company with gobs of computing power and Python expertise, such choices contain no meaning.
Team Collaboration and Level Means You Can’t Always Use Cool Techniques
Another important thing about context is that your team plays a big part in it. The entire WordPress ecosystem is rich with “dumb” procedural code. This seems, at first, like an obvious weakness. Few people in favor of academically “good” code advocated for procedural coding styles for much other than performance reasons.
But because of the more simplistic and linear needs for a human to make sense of procedural code, it’s pretty clear that WordPress serves as a gateway into programming for so many people simply because it is procedural in nature.
Similarly, “functional programming” is surely the “latest hot paradigm.” (No, I do not need a history lesson. Thank you.) But I wouldn’t try to explain “endofunctors” to a new programmer from any background but pure mathematics before they’d come to terms with the basics of how and why procedural code works (and doesn’t) across different contexts.
We Must Acknowledge Shared Context So We Grow New Group Contexts
The final thing I’ll add is that once your recognize that you yourself, or your community of practice are doing things to support a different context than you really are in, you can and should work to improve standards and push for great skill and beauty of code in its specific context. I think once you know that a project is “a Python website built by a Python team,” getting to the nitty-gritty of what “idiomatic Python” is is both sensible and good. But until you’re at that point, discussions about it are a waste of time.
And it’s also only by knowing that you’ve fully planned around each person’s personal context that you’re able to evolve the ground context of the code to the point that you see the value, purpose, and meaning of “endofunctors.” (I’m personally not there yet, and may never find such a context personally.)
There’s a Lot More to Say About Code Context…
For now I hope I’ve made my point about the importance of understanding and acknowledging the human context around our code. Without seeing it we’ll spend all our time wastefully talking past each other about all the other elements of what thoughtful code truly is. So to have any meaningful discussion about code, we must root that in the code’s context. Without that any other points are useless.