We were thinking about words for code. Let’s consider these. New! Improved! Now with more words!

Brian Marick has a story that he uses from time to time in his talks. Brian’s wife Dawn is a professor of large animal medicine, and one of the things that students have to learn is a diagnostic notion, whether a cow is “bright” or “dull”. Bright is good, dull isn’t good. The tale gets to be quite fun, and the upshot is that there is no firm definition of bright vs dull, but the students ultimately learn to diagnose cattle as bright or dull.

They learn almost entirely by examples. Check this animal, is it bright or dull? They guess “bright”. No, it’s dull because it isn’t cleaning its nose. (Don’t even think about that.) How about this one? No, because … and so on. After observing many examples, they have the concept of bright vs dull very solidly, but still no one can firmly define it.

So in Tuesday night’s Friday Coding Zoom meeting we were thinking about terms for “good” code. Chet Hendrickson suggested “bright” and “dull”. It turns out there are a lot of useful metaphors around brightness, light, and so on. Code might be a bit dim. We might shine a light on some chunk of code. We might brighten up that method a bit.

There are other words, of course. I use the word “clean” frequently, to the point where I feel I should use it less, since the word has been given a fairly rigid meaning in the literature, even though I mean it quite generally. I might just as well say “nice code” or “good code” or “habitable code”.

Some folks will probably feel that we should come up with a strong definition for our term, whatever term we pick. I think that’s impractical: our views will always differ on the fringes of an idea like good code. Instead, we consider examples of code we prefer and code that we do not. We take code that we don’t entirely like and we make it “better”. We make it less dull. We make it more bright.

We’ll never have a solid definition for good or clean or bright. But what we can have is a growing common understanding of the kind of code that lets us progress at a steady, even improving pace over the course of our development effort. In fact, among my colleagues, my gang, my friends who are engaged in helping teams do good work, we do have a very solid common understanding, There are many heuristics that we use: SOLID, Kent Beck’s Four Rules, High Cohesion and Low Coupling, and so on. By and large they all tend to lead us to code that we all agree is bright … and when we see a dull bit and offer an improvement, we all generally agree.

Of course, if you read my stuff, you see me working all the time to keep my code bright enough, in the face of all the changes I need to make, all the mistakes I make, and all my general inherent dullness.

Bright or dull? Let’s try for bright.

Wednesday AM

The above was blurted out last night, while the Zoom meeting was still going on, in hopes of irritating my friends. That having been accomplished, I was able to go to bed happy, at least as soon as the Diet Coke wore off.

This morning as I woke up a bit, I was not comfortable curled up in a ball or whatever, and the word “comfortable” came to mind. I though that word was rather expressive, and then I thought “expressive”.

Let’s riff on words to describe code, what they connote, what’s good about them, what’s not so good.

This was Bryan’s favorite, and he would not be swayed. And it’s a good choice, isn’t it? Code is Clear if we can understand it readily. It’s Clear if we can recognize what it is at a glance or from a distance. If it isn’t clear, it might be, well, unclear, or muddy, or dirty.
Code is Comfortable if it fits readily into our mind, uncomfortable if not. Those Python collection idioms are comfortable–if you’re used to them. They’re uncomfortable if you’re not. Maybe you should become comfortable with them, and if you encounter them often enough, you probably will. Or maybe we should all agree to use only the ones we’re all cool with.

We’d probably like to be comfortable in a wide range of code styles, languages, and idioms. We’d probably do well to expand our vocabulary, advance our syntactic skill, increase our ability to craft sentences, paragraphs, chapters, books, and generally spiff up our grokking of the world of code in all its beautiful hideous strangeness.

Code is Expressive if it says what we were thinking when we wrote it, and when it puts that thought into the mind of the reader when they read it. When code is not expressive, we often have to read it slowly, almost executing it in our mind, and then suddenly we look at some chunk and cry out “I see what he’s doing here!” That’s not a good thing. It tells us that the code is not expressive. It might be opaque, muddled, vague, or wandering. It might use variable names like doggie and piggie when income and expense would have been more expressive.

One of Kent Beck’s Four Rules of Simple Design is that the code expresses all the design ideas that make it up. The others are that it runs all the tests, contains no duplication, and minimizes programming entities like statements, modules, and objects. We wouldn’t want Expressive to exclude those ideas.

If you can live in it, it’s Habitable. The better you can live in it, the more habitable it is. Perhaps the word is a bit unusual. That could be OK, because if we could have a relatively unique word that we could associate strongly with our ideas, it might be better than a more common word, like, say, “clean”, which carries lots of baggage. On the other hand, we don’t want to look for too strong a “definition” of this idea: it has to encompass a wide range of quality and a wide range of techniques that all come together to make code merit whatever term we pick.
Someone suggested Tight code. I object that tight often means small, as small as possible. I envision chunks of assembly code that you can’t begin to understand until the author tells you that register B contains the status mask from the previous function, and that three skip instructions in a row select five out of eight cases. And then you still can’t understand, and start wishing for more memory.
Here again, the connotation of “small” can be troubling. Code should be as concise as it can be, subject to expressing what it does, subject to the reader being comfortable, subject to remaining habitable.
I’m not alone in being troubled by this one. Too much polishing is a concern for many managers, who want the thing shipped and if some internal part isn’t quite shiny enough for you coders, get over it. And I’d have to admit that sometimes I might polish some bit too much. When I do, I’m working within my craft to figure out, not how to make this bit of code perfect, but how to code better in general.

I don’t think I’ve ever seen a product in trouble from too much polishing, but I’ve seen plenty of efforts fail because the sponsors ran out of patience before we shipped. That’s why I recommend what I recommend. And I recommend against Polished as our term.

Too vague for my taste, though I do think of coding as a craft that can be done brightly, brightly, and with beauty.
Too vague.

Have You a Point Here, Ron?

Was there some rule that I had to have a point? The point was to explore some words that we might use to describe code, and to get a sense of what they might mean now, what they might come to mean were we to use them frequently and consistently. A sub-point, if there is such a thing, is to prime my mind to use better and more descriptive terms for code when it needs improvement, and when it gets what it needs.

As I think I’ve said somewhere, I don’t believe that it’s even possible, much less productive to come up with a strict definition for what code is or is not worth of whatever term we pick. That’s no more possible than a definition of what makes a good poem or a good orchid.

We have very few words that strictly define matters of quality. Quality is what you like, according to Phaedrus in Zen and the Art of Motorcycle Maintenance. In many things, perhaps most, perhaps all things, thoughtful minds may vary on what makes up code quality … and yet we often find common ground among our peers.

There may be multiple camps. There will almost certainly be different criteria for code written in languages with strict type declaration versus languages with dynamic typing, or in functional languages versus object-oriented languages vs procedural languages.

I find myself in a camp with the wonderful characteristic that when we all look at a piece of code and someone proposes a better way of writing that code, we almost always agree that it’s better, and when we disagree, we find that with a bit more crafting, we usually come up with something that we can all agree is quite clear, expressive, comfortable, and habitable.

And we all agree that it could be better, and that it’s time to abandon that particular bit of code as Good Enough.

Like this article. Good Enough. For now …