Adventures in npx and the Philosophy of Good Code

Hello, world!

Trying to put together this website was like trying to put together a house with a glue stick. Somehow it's holding (for now), but my god was it painful.

I've been slowly starting to work through Pico's Heavy Wizardry 101, and I've been having a lot of fun with it. I was even inspired to write a dig against Elon Musk and upload it as a git repo at git.elfilosofo.net/hello-world.git. Check it out, if you want; but to cut a long story short, I reduced the size of a hello world program from some 78k to 400 bytes. I stripped headers, merged binary sections, removed comments and build info, and eventually eliminated the C library altogether—that is, as well as learning what all those things mean! Say what you want about Assembly, but it is simple. It is so simple, in fact, that it defies common sense. Now compare that with my next day's project of putting this beast of web 1.0 nostalgia together, and you'll understand why I have appreciation for it.

At the bottom of the page, you'll see a little tag telling you that this site was built with 11ty. That's true. And I'm very grateful for the tools, the tutorials,etc. Still, it was agony for me. The builder uses several different kinds of coding languages to stitch everything together, and it's not always clear what the syntax is supposed to be. The way I described it in my doc files captures the experience fairly well:

Imagine speaking French to someone only for them to reply in Italian, which you respond in, but then it's speaking Spanish. Welcome to web dev. That's what it's like.

I'll grant you that I'm not a web-developer, or even particularly talented as a programmer. I'm very much learning. Nevertheless, having been tempted to put my head through a wall, I instead did the healthier thing, and started to ask myself what I thought "good code" should be; and sure, there is an element of what I have to say that is eminently concerned with what I value. I'm not going to sit here and pretend that I'm somehow the arbiter of a world of which I have a very small part. There are programming legends who might push back against something that I say, or who may at least offer more nuance or insight into the languages themselves and how they can be used. But maybe, at the same time, there is insight in hearing from someone like me, who isn't buried in this stuff from dawn til dusk. I hope that's true, and that even if you disagree with what I say, you at least find it constructive or thought-provoking.

Preamble

One of my earliest lessons in programming was that the term itself can be quite broad. In grade eight, I was excited to finally get to use programming in our class, but I was disappointed to find that this meant using Scratch. By that point, I'd played around with a few programming languages like Java or Python or JS, so Scratch was child's play—not something I thought of as "programming". And you know, despite my own disappointment, that was kinda the point. Scratch exists to teach learners the basic structures of programs using an intuitive drag-and-drop interface. You don't need to look through docs or google solutions to problems. What you can make it limited, but you're learning to think as a programmer thinks: through loops, evaluative statements, objects, functions, etc. And for kids, that's great! Power to them.

How many other types of "programming" exist in our world? We talk about things like programming a remote, but most times we tend to avoid the "programming" language because something doesn't involve code. Usually, this is at the highest level you can possibly get without passively or not interacting with a system at all. For instance, you can program your alarm to go off at a certain time, or your phone to play a particular ringtone when a particular person is calling. When you think about it, anytime you give a system instructions how to behave under certain conditions, you are programming it to do something.

Like Scratch, this has limits that exist within the confines of a system, which you can perhaps break or bend, but which is eminently the rule. If you want to change that rule—for example, if you not only want your phone to play a ringtone but (and this is silly!) dance/vibrate to its tune and send a text to the caller with the song lyrics—you're going to have to get creative. You could call this meta-programming, if you like, since you're changing the rules of a system; but that doesn't really matter. What matters is that programming can mean many things that we don't ordinarily assume it means. (You could say, my use of the term exploits a linguistic ambiguity vulnerability and injects a new understanding.) But at the end of the day, programming will boil down to working with conditions, logical operators and evaluators, and functions.

The Problem with Your Remote Control

Imagine a brand new, blank remote control. The annoying thing about learning to program it is that it's only really useful for this one remote (and probably only that one model of it). It feels like a waste of time because you can't use it anywhere else. You're just teaching it to recognize your instructions so it can do something you actually want it to do, but then you get a new remote control or TV set, and you have to do it all over again. Yay.

So let's put ourselves in this situation: what would make this easier? I can think of a few ideas:

• If models of the remote emitted a standard set of signals so TVs could (attempt to) recognize their instructions out of the box.
• The ability to export configurations en masse so they can be imported and remapped onto another remote.
• Good documentation, so we're not stuck guessing what we have to do to program the remote in the first place. That's just off the top of my head. This may seem a far cry away from computing, but already we can see a few things that make programming easier and more valuable to know:
• Interoperability: diverse tools can communicate with each other easily because they operate according to a common standard. (Tracking my metaphor earlier, that would be like two people speaking and responding to each other in one language.)
• Portability: the ability to take and move your code for use elsewhere when it becomes useful.
• Documentation: this one's still the same. Good documentation has always been valuable with new technologies. Given these three things, programming my remote control doesn't seem such a waste of time since it can be re-used and applied elsewhere in a predictable way.

KISS

By extension, we may infer a fourth principle of good programming: simplicity. Of course, in this context "simplicity" is a term relative to the complexity of the system that it describes, but it applies nonetheless. If I had to break-dance to properly program my remote, I would probably have to pay someone else to handle it for me. Now that's obviously ridiculous, so let's consider a real life example to demonstrate.

Morse code was cutting edge for its time and is well worthy of note in the history of technology. But you've got to admit, it is rather hard to understand. Imagine we spoke in Morse code: instead of English, we are now reduced to caveman grunts, long or short, for the time being. How do you imagine that would affect the quality of our conversation?

• We would spend a lot of time flipping through references to decipher each other's grunts.
• Similarly, we would spend time translating our own thoughts into long and short grunts.
• We'd spend more time grunting at each other than we would speaking.
• I give up.

Come to think of it, this is probably why cavemen didn't leave us with a plethora of literature. Until the tools were developed to convey complex thoughts in a more convenient way, the technology of our communication would be limited by our means to communicate. Is that a circular claim? Yes, I'd say so, but it just goes to show how technology adapts to humanity and vice versa. Words may be more complex, but they are also more simple in that their meaning is intuitive to us and well-suited for the task at hand. That's why I say, "Keep it simple, silly."

Okay, so we've established that the written and spoken word is preferable to caveman grunting. What does any of this have to do with computers?

Grunting at Silicon

Programming isn't like talking to another human being. Human beings, at least in their native communities, have a lingua franca they can rely upon to communicate effectively. Even if our tongues differ, there are symbols common to our experience that we can use to make sense of what someone else is trying to say. Maybe the best (and one of the most dramatic) examples of this is putting our hands to our throat to indicate that we're choking. That simple act of displaying symbols does a lot to communicate without the use of more abstract words:

• The placement of the hands indicate the source of the problem.
• The motion of the hands indicates the pressure of choking.
• The context shared by human beings (i.e., that we understand the possibility and danger of choking) implies the rest of the message.
• The sound of choking, too, indicates that you're choking.

This is something that we can surmise as human beings, but we do not share the same context with machines and (probably) never will. Not to mention, we have entirely different hardware: we're carbon-based, they're silicon-based. That's an entirely different way of existing in the world. So I can promise you now that if an android is ever at the dinner table (where it's hanging out just to be polite), we would have a hard time understanding what it's trying to tell us when it short circuits. And that's where programming comes in!

Imagine we're at the dinner table with an android, who has short-circed. If he were to communicate with us in our native language, he might say something like this:

010010001100011111000000000000010000000000000000000000000100100011000111110001110000000100000000000000000000000001001000100011010011010000100101001011110001000001000000000000000100100011000111110000100000111000000000000000000000000000001111000001010100100011000111110000000011110000000000000000000000000001001000110001111100011101000101000000000000000000000000000011110000010101101000011001010110110001110000001000000110110101100101001000010010000001110011011010000111011101100100011101000010000001100011011010010111001001100011011101010110100101110100001000010000101000000000

Yeah, I wouldn't know what he wanted either. But now imagine he had a translator that helped him to bare his soul for us. We'd end up with assembly instructions to print "help me! short—". That might be a bit confusing still, so add a couple more translators on, and we'd have something looking like a C program or a Python script. Even if we were to adopt caveman grunting in an effort to communicate in binary, we'd still need to explain to the android that long_grunt=1, short_grunt=0. And we would probably communicate that too slowly to save them. (Poor fellow!) This is all computer programming is at its lowest level: a stack (pun intended) of translators between us and the processor, so it knows what we're talking about.

If we want to think about it in this way, we might think of another principle of good programming: brevity, not to be confused with simplicity (which has more to do with the organization of a system than the length of instructions). In philosophy, there's a long-running joke that you shouldn't say in 100 words what you could say in 1000. (In reality, brevity was encouraged in our writing—isn't it obvious?) We are fortunate in computer programming that CPUs don't angrily tell us to get to the point because some code can be quite verbose and could be reduced to something much shorter. This would make debugging much easier and manage memory more efficiently. Our android would thank us for it.

Concluding Thoughts

Unfortunately, my adventures in npx haven't quite panned out this way. A multitude of backwards compatibility layers, plugins, and programming languages each talking past one another has seen to that. Although, in fairness, this isn't really the fault of 11ty, or any other static site generator. As I said, simplicity is something relative to the complexity of a system, and my-oh-my is the web complicated.

But I hope what my adventure shows is that it's not just about sparing yourself a headache. Good code has philosophical implications not just for the way we interface with technology but how technologies interface among themselves.

Interoperablity allows larger ecosystems and communities to flourish.

Portablity allows people and tools to collaborate.

Documentation lowers the barriers to entry for those who wish to create cool things.

Simplicity creates transparency in systems, fostering accountability.

Brevity helps keep things simple, and leaves less room for error.

This isn't a political manifesto, but insofar as we increasingly rely on code for our political, social, and economic arrangements, I do believe it has political consequences. How we code is almost as important as what we code, and if one believes there is an art to programming, it is high-time we embrace this.