by Thursday Bram

When explaining programming concepts, metaphors are crucial: most of us don’t automatically grasp every concept necessary to make programs work. Metaphors let us connect new material to concepts we already understand. But the metaphors that are often used to teach programming concepts are not automatically accessible to every person who wants to learn to write code.

We pick metaphors from our own experiences. Are you a sports fan? Then your metaphors of choice might reflect how a ball is passed. Do you like to work on cars? You might explain a concept in terms of an engine. Or are you into woodwork? Comparing programming to carpentry could make sense.

But what if you aren’t used to working on cars or following sports? Metaphors that don’t make sense get in the way of learning, especially when we’re talking about abstract concepts like programming.

Bad Metaphors Make Teaching Harder

When talking about programming, I pick on git because the metaphors I’ve heard during explanations of different git commands tend to be convoluted—often making an explanation far harder to understand than the underlying concept. Teaching the concept of rebasing code in git, for instance, can include metaphors like time travel, tree grafting, and meat cleavers. That last one is my least favorite, but is quite popular:

“Thanks to Travis Swicegood, we have a better metaphor: A cleaver. Rebase helps to cut up commits and slice them into any way that you want them served up, and placed exactly where you want them. You can actually rewrite history with this command, be it reordering commits, squashing them into bigger ones, or completely ignoring them if you so desire.”

If you haven’t had much occasion to use rebase, that metaphor sounds easy enough to understand: you chop up the order in which you made changes to a particular code base. But the metaphor breaks down quickly once you get into what git rebase really does. (The meat cleaver metaphor also doesn’t seem to be a big hit with vegetarians.) I feel like a few people heard this metaphor and ran with it without asking for a lot of feedback on how their audiences responded to the concept of the meat cleaver.

In the git documentation, git rebase is defined as “Forward-port local commits to the updated upstream head.” That definition is about as clear as mud. It’s hard to do much better without resorting to metaphors and examples. For our purposes here, though, we can work with a basic definition: git rebase rolls back changes we’ve made to a code base and then reapplies those changes in a new order. Leave the hairy mechanics for another day.

With that definition, we can easily see how weak the cleaver metaphor is. As well as taking apart the order in which changes are applied to a code base, rebase also lets us reapply those changes in another order—when you take a cleaver to a piece of meat, though, putting the resulting pieces together again later is no simple matter.

Naming Conventions Shouldn’t Be Metaphorical

The problem of unclear metaphors goes deeper than describing programming’s key ideas to newcomers—it’s not just a matter of complex explanations. Git is a mish-mash of bad metaphors long before you get to the underlying concepts. Git’s commands read like a list of metaphors for the work each command is supposed to perform:

  • fetch
  • cherry pick
  • pull from upstream

These commands, taken out of the context of version control, conjure up mental images of dogs and bones, selecting good fruit, and even fishing. While knowing the idioms preferred by git’s core contributors isn’t necessary to use it, that knowledge certainly helps. Not knowing the underlying metaphors or context for these commands makes learning them just a bit more difficult.

We’re never going to have commands (or other naming schemes, for that matter) that are completely without metaphorical meaning — in fact, making up completely new terms would require using nonsense words. But we can do better in terms of choosing the subtle metaphors that go along with naming individual commands. For those of us who are creating tools we expect other programmers to work with, we need to pay attention to the other types of knowledge we’re subtly referencing. If you’re starting from scratch in developing your naming scheme, spend some time on the matter. Just being aware enough of your naming scheme to stick to a connected set of metaphors, rather than mixing fishing and fruit harvests, can be enough to make a tool more accessible.

Some communities have established naming schemes, of course. In Python, you’re going to see bundles that are called ‘eggs’ which you get from the ‘cheese shop.’ You’re not going to be able to rename anything that doesn’t make sense if there’s already a well-established set of metaphors in place. In those cases, stick to naming conventions and keep your alternative metaphors in documentation and other materials outside the code itself (no matter how much better your metaphor might be).

For those of us who don’t feel advanced enough to release tools to our fellow programmers, there is still plenty of work to be done. Finding new metaphors to describe git’s more complex commands (as well as other programming concepts) and sharing them with our peers is crucial. Give talks, write blog posts, even annotate existing tutorials to make them useful to anyone with a similar background to your own. Need a place to get started? Write up a response to a programming metaphor you hate. You don’t have to publish it, but you can share your feedback with the people publishing those metaphors.

Sharing your own metaphors doesn’t have to be complicated: the only reason I really understand how an algorithm works conceptually is because a friend gave a short talk at a user group several years ago, walking through souffle recipes as algorithms. That mindset has stuck with me for years and I’ve used it in articles, as well as to explain individual algorithms in meetings and discussions. That’s because I cook, even if I don’t make souffles all that often — that shared experience means that the recipe metaphor made sense immediately to me.

Metaphors Reflect Our Culture and Our Experiences

These sorts of metaphors don’t just make learning new concepts harder, though. They can wind up dictating the culture that we see every day in the software industry.

Katie Lane, a lawyer, dealt with software vendors who didn’t think very carefully about the metaphors they used during sales meetings. She says, “Software sales guys always used ‘open the kimono’ for ‘let me tell you what’s really going on.’” As far as metaphors go for revealing information, asking someone to ‘open their kimono’ and metaphorically show off their underwear is creepy. Lane did find a way to educate those software vendors with a metaphor of her own: “I started using ‘unzip the fly’ in retaliation. They usually stopped after that.”

When a metaphor becomes common, people use it unthinkingly. A useful metaphor provides a cognitive shortcut, something that a vendor, an educator, or anyone who routinely finds themselves explaining tricky concepts needs desperately. But we need to carefully consider the metaphors we use, both in terms of whether a listener will get the metaphor but also if there are going to be negative connotations for that listener. Customizing explanations to individual audiences is a big part of being an effective software vendor (including promoting open source projects). The same holds true for writing documentation and tutorials. Think about your audience’s experiences, as well as your own.

Through my own experiences, I’ve found metaphors that help me illustrate concepts in a way that I (and people who have had some similar experiences) can grasp more easily. Return to the concept of rebasing for a moment: while meat cleavers and tree grafting don’t provide me with a clear view of how rebase works, the idea of a seam ripper does. A seam ripper takes apart a piece of clothing without destroying the fabric so that you can put those pieces back together slightly differently — maybe cutting down the fabric a little to make clothing fit better, maybe just to resew a seam that’s crooked, or maybe to take apart a piece of clothing and turn it into a quilt.

Of course, my metaphor requires knowing what a seam ripper is. It comes from a specific set of knowledge that I can draw comparisons to. There aren’t a lot of universal sets of knowledge. I’ve heard suggestions that we could talk about git rebase in terms of a sandwich: you can take off cheese or lettuce off a sandwich, reorder the ingredients, or even cut it in half without violating its inherent sandwichiness. In much the same way, you can remove or reorder commits to a code repository using git rebase. It’s not a perfect metaphor, but a sandwich may be clearer to many users than a seam ripper. Cooking and eating are closer to universal, but those areas of knowledge just reinforce our need to explore what metaphors we use and to test how effectively they work.

Beta Testing A Programming Metaphor

Building better metaphors into how we talk about programming, as well as how we teach concepts and name tools, has never been more necessary. More and more people are learning to code — or at least trying to, until a key concept seems impossible to understand. Code schools, online courses, and even elementary schools are introducing learners to programming. While the reach of these educational opportunities is impressive, many of the educators responsible for teaching programming to wide audiences are still relying on the metaphors that worked for a group of students in a college-level computer science course or for a self-taught hacker able to sink in hours of programming practice every night.

I’m not saying that there isn’t room for car metaphors or even comparisons that rely on unfortunate meat cleaver references. But we need a lot more metaphors sprouting from a much wider variety of experiences. We need comparisons to cooking, rap, Legos, and a million other things.

And we need feedback on the metaphors we’re putting out in the world. We need to beta test the way we make explanations: asking people with different backgrounds from your own is the only way to know whether an explanation is accessible. Unless you happen to be a mind reader, asking is the only way to find out the value of a given metaphor. After all, there’s no other way to find out whether someone else has any experience with cooking, car repair, or whatever else you might use as the basis for a metaphor.

Thursday Bram writes about technology for publications ranging from Bitch Magazine to Entrepreneur. You can find Thursday at her website,