I’ve been thinking a lot lately about what makes code “good.” Let’s take it for granted that “good” is so meaninglessly subjective that it’s not really a useful term for one to use when talking about a program or block of code. So let’s say that “thoughtful code” is code that meets my personal subjective definition of “good.” But before you zone out, I want you to know that a lot of “bad” code is actually “good” and vice-versa. The counter-intuitive reality is that WordPress contains some of the best PHP code on the planet. Let me explain why…

In short, Thoughtful Code has four qualities: it is contextual, intelligible, verifiable, and cellular. We’ll take them one-by-one.

What does it mean for code to be “contextual?”

The first thing that makes assertions that a specific line, block, library, or framework of code is “good” into meaningless wastes of time is that we don’t first define the context in which the code will operate.

It is obvious, to me, that if you’re writing code that needs to be tweakable by a sales person at your company, anything in a language more complex than Microsoft’s Visual Basic is a mistake. (No offense intended, salespeople. You have many other valuable skills.) You expect that person be able to use your “beautiful” C++ code, and you’re a fool and a jerk. I don’t care if in the context of C++ lovers your code is good, you are a fool.

Code is only as useful as it can be in the context in which it is applied. This is also why code that is used to launch a nuclear weapon is unlikely to ever be “thoughtful.” I suppose some low-level systems code that is used in that effort could coincidently be unscathed by its use their, but the moral context of that code does certainly affect it.

To a large extent, this idea that code is only good when it serve well the context in which is deployed is simply an effort to subvert a lot of useless sniping about “good” that we’d otherwise be suffering through. Though I do think it’s a little deeper than that, I’ll save the deeper nuances for another time.

The Basics of Code Intelligibility

After code is an adequate match to its context, the next quality that code should have is intelligibility. I started calling this a requirement that code be “understandable”, but then it was pointed out to me that launching a nuclear missile can indeed be “understandable” even when it is in response to a minor romantic slight. So “intelligible,” while being a little too hifalutin for my taste, is less commonly used in the context of “merely comprehensible” that “understandable” so often is in my vocabulary.

Code that is “intelligible” makes sense. The second reason that “intelligibility” inherently and necessarily be presented after “contextual” is that code is only intelligible in a context. I was recently dunked in the deep-end of the Amazon Web Services (AWS) ecosystem. What I found was a sea of mediocre interfaces and jargon (especially acronyms/initialisms) so deep it made my rather-aware head spin.

Similarly what makes sense in the context of a Python program may be nonsensical to someone writing C. These two languages share a lot, but they’re often written with very different goals. Where C is often used in contexts where performance is critical and real-time is a must (and so most optimizations aren’t so “premature”), Python is more often appropriately written for broad approachability and comprehensibility from many comers who aren’t familiar with specific desired performance criteria.

What It Means To “Verify” Code

Once code makes sense, the next quality I want it to have is the ability for me to quickly and easily verify that it works correctly. In programmer contexts, this would often and properly be understood as a robust and complete testing suite that extends as low as a single functions and also across the whole of the system being successfully orchestrated together. Both are within the purview of this level.

It is not by accident that “verifiable” comes after “intelligible.” I would almost always prefer to pick up code that I couldn’t easily verify that I could understand the purpose of. After all, even if code doesn’t self-verify, after I understand its intent I can manually verify it. Verifiable but non-intelligible would let me verify it did something but struggle to discover what.

I’ll also add that verifiability can be much more simple than automated tests. I’d consider spreadsheet-formula-writing to be “programming” and I would consider that stuff verified pretty adequately be a “sniff test” where I simply agreed that “those five well-labeled intermediate figures all seem about right.”

How to Understand “Cellular” or “Atomic” Code

While all the letters of the Thoughtful Code acronym are still dynamic, and have changed since I initially thought of “CUVA”, this one has been the hardest to let go of. “Atomic” and “cellular” are subtly and importantly different. “Atomic”, especially in science circles, is meaning something like “as small as possible, indivisible” where cellular is also “quite small” but also “able to live independently” and “to collaborate seamlessly.” But while CIVA is a pretty good evolution of CUVA, I’m less sold on CIVC.

Anyway: for code to be the best, once I know it works, I want it to be divided into independent, self-coherent, and useful units. I want it to be cellular in the sense that all the parts of the system do collaborate together — to make anything from a bacteria to a human body — but can also be examined and found useful on their own. Cells do not, generally considered, have phantom quantum entanglements with other objects in the ecosystem they inhabit. Most programs do.

This is a Work in Progress

I think this list, and the “CIVC” acronym doesn’t capture the full array of ways I want code to work perfectly. But it’s the best approximation I have so far of my value-system around software. “Does ‘cellular’ mean a dependency manager is good or bad?” is both an interesting question and one I don’t have a clear answer for today. But I’ve been working on this framework for a while, and asked a few readers about it. So now I’m asking the rest. Is this framework useful to you? Is it interesting?

Oh? About WordPress. Well, its parts aren’t very cellular. While it has automated tests of some hundreds, I wouldn’t say that I (as not-its-developer) trust them. And much of the code is manifestly not intelligible to most modern programmers in the languages that WordPress is written. But it’s good because none of those qualities matter in its context. What’s its context? Its context is end-users who want the easiest, cheapest software they are able to pilot to make pages online. WordPress is that, so almost all other code quality metrics don’t matter.

And on that, I’ll leave you. Enjoy 😝