A Foo walks into a bar and gets bash'd in the baz

Some time ago, I published a blog post on Closure in JavaScript. In the post, I touched on why I deliberately shied away from the foo bar baz bash variable names so often used in code examples. I found them to be very confusing as a beginner. It turns out I'm not the only one:

I also had a few comments from folks on Reddit:
"Heck, they are still confusing for me, even if I know that it's just a naming convention. Unless an example is shorter than 5 [lines], one should never teach with foo and the [lines]."

"IMO even a, b, c is better than foo, bar. Anyway, I always try to use reasonable names for variables."

"I'm aggravated when I see it too as I think why do this? Why not do something else? Sequacious and annoying."

An Example

It's common to see something like this when looking up an example of a programming concept

var foo = {
    bar: 2,
    baz: {
        bar: 1,
        bash: function() {
            return this.bar;
        }
    }
}

var qux = foo.baz.bar;

console.log(qux());
console.log(foo.baz.bar());

When I first started programming, I'd heard of bash as a shell and thought certainly foo bar baz must be some special keywords. Turns out I'm not the only one, there are a number of Stack Overflow questions similar to "What is the meaning of foo, bar, baz, etc"

I understand now they're intentionally nonsensical, and there's a whole history behind Foobar and its usage. But it takes a fair amount of context and prior knowledge to make sense of them. Foobar is also distinctly American in origin. Using these examples can make your code even more confusing to new developers around the world.

What if, instead, we sought to use more practical and international examples that couldn't be part of the programming language. Variables and function names that are either related or unrelated implicitly.
For example, a salad:

var salad = {
  greens: 'mixed',
  vegetables: {
    tomatoes: 2,
    carrots: 1,
    getVeggies: function() {
      return 'carrots: ' + this.carrots + ' tomatoes: ' + this.tomatoes'
    }
  }
}

var saladVeggies = salad.vegetables.getVeggies;
console.log(saladVeggies());
console.log(salad.vegetables.getVeggies());

It's much easier to distinguish which parts of the code example are language syntax like var, this, return, console.log, etc, from the parts that are replaceable.

Maybe for you, the salad example is just as easy to understand as the foobar example because you've been doing this a while. I get that. But the salad example is going to be, at a minimum, equally understandable, more often more understandable, for a broader audience.

Here are a few ideas for examples that can be more relatable to a wider audience:

• Food: Salad is one of the most popular foods worldwide, pizza is another. Lots of cultures have a concept of a sandwich or something similar.
• Buildings: if you're talking about food, you can talk about a restaurant and the people who might work there. Maybe a chef as a factory function that creates salad objects. Or talk about how diners know about the walls and roof as a demonstration of scope.
• Cars: great for showing OOP concepts, inheritance and interfaces. All cars have a go and stop method but the seats, engine, etc can vary from a 'deliveryTruck' to a 'sportsCar'.
• Music: how about demonstrating functional programming by way of an orchestra? const concerto = () => withPiano () => withViolin () => {}

My point is that, while it will take you a bit more thinking to come up with an example that is relatable to your audience, it can save a lot of cognitive load on the audience and make your example more understandable. It will go a long way to making your blog posts and code more accessible to a wider audience. We all have to read documentation frequently, the easier it is to read and comprehend, the better off we all are.

If you have any favorite go-tos when writing examples, please share below!

Comments

[Idan Arye]

I think the main point of using nonsensical names is to prevent the pointless dispute that more meaningful placeholders may invite. People will try to argue with you about why your salad doesn't have cucumbers, but no one will be irritated about your baz not having a qux and they may, instead, discuss the actual programming concept you wanted to demonstrate.