Code examples: it’s time to raise the bar

Black-and-white image of laptop displaying code along with a mug that reads "Keep calm and drink coffee" and an open notebook with a pen laying on tit.

If you’ve been writing code for even the shortest amount of time, you’ve most likely come across foo, bar, baz, and maybe even qux (and beyond). Technically termed as metasyntactic variables, they’re used as placeholder names for example variables in code, for want of a more fitting or sensible word or phrase. These ubiquitous nonsense words crop up in many reputable and well-used resources for programmers, including some of the highest -rated StackOverflow answers and the official PHP documentation.

Originating from U.S. military slang, the terms “foo” and “bar” are so well-known that the Internet Engineering Task Force even released an RTF explaining their etymology and use. The phenomenon of the use of meaningless placeholder words isn’t just confined to the English language either. The Hacker’s Dictionary gives many foreign examples of metasyntactic variable names, such as toto, titi, tata and tutu in French, and pippo, pluto and paperino in Italian – pippo and paperino being the Italian names for Goofy and Donald Duck.

The reason for using foo, bar, baz etc. in code examples makes sense on the surface – for the sake of a few throwaway lines of code used to illustrate a simple concept such as finding the sum of two numbers, one does not care what the two numbers might be, or why they are being added together. In this case, writing a one-line example such as the below is perfectly acceptable.

public int AddNumbers(int foo, int bar)
{
   return (foo + bar);
}

However, once fledgling programmers grow familiar with the most fundamental concepts and move onto more intricate, object- orientated ideas such as inheritance and virtual methods, foo and bar start to become less suitable. Consider the following example:

public abstract class Foo
{
   public virtual void Baz()
   {

   }
}

public class Bar : Foo
{
   public override void Baz()
   {
      // Do Bar stuff here
   }
}

Although perhaps not immediately obvious, the purpose of this code is to provide an example of an abstract base class with an overrideable method. While the syntax is correct, the names of the classes and method simply don’t make sense. What is a Foo? Why can’t I create an instance of a Foo, but I can create a Bar? What is Baz supposed to do?

Now consider the example below:

public abstract class Animal
{
   public virtual void Speak()
   {
      // To be overridden
   }
}

public class Dog : Animal
{
   public override void Speak()
   {
      Console.WriteLine("Woof!");
   }
}

In this example, the names of the classes illustrate the underlying concept of abstract classes and inheritance much more clearly. Everyone knows that you can have a dog, but an animal is an abstract concept; – a type of living being which all dogs happen to be. Giving the overrideable method a relevant name is also a nice touch; it helps capture the imagination of the still-learning programmer.

The problem with using foo and bar to illustrate more advanced concepts is that it gives the reader two things to mentally process; not only must they understand and learn the syntax, but they must also try to imagine the real-life problem or scenario in which they would use the concept. Ditching foo and bar in favour of readable, recognisable and sensible variable and class names lightens the load on the reader, helping helping to deliver the idea being described in the code.

As for programmers who use foo and bar in production code… just don’t. Please.

 

About the author