In this article, I’ll try to convince you that using meaningless placeholder words in your software documentation is very unfortunate idea.

My Personal Struggle

You might wonder why the hell do I spend time writing this post at all. Surely, meaningles placeholders can’t really be that big of a problem, right? Well, I think they are.

For example, a week ago I had been reading docs for a new dependency injection library and I found them surprisingly clear. Then, at some point, I reached a code snippet which used Foo and Bar, and my brain stumbled. I just can’t find another way to describe this strange experience of gradually building a picture of a feature in my mind, and then having this picture evaporate the moment I saw these meaningless placeholders in code. The sole act of reminding myself that Foo and Bar have no context made me go back an re-read the entire page.

The odd thing here is that I read a lot of software documentation and, by this point, I should’ve gotten accustomed to Foo’s and Bar’s. However, it didn’t happen. Presence of meaningless placeholders, even the “standard” ones, still makes docs more challenging for me.

Comparison to Lorem Ipsum

Following my recent encounter with Foo’s and Bar’s, I’ve been wondering why my experience with these placeholders is so much different from Lorem Ipsum placeholders. The later doesn’t bother me at all. Sure, I had to look up what the hell Lorem Ipsum means the first time I saw this text, but, since then, I’ve been totally all right with these placeholders. What’s my problem with Foo’s and Bar’s then?

I think it boils down to the fact that I never read Lorem Ipsums in UI mockups, but I have to read every single Foo and Bar in docs. I just can’t skip them because they are integral parts of these several lines of code that I need to understand. Moreover, quite often when I read software documentation, I go straight to code examples and try to figure it out from there. In these cases, meaningless Foo’s and Bar’s become among the most important parts of software documentation.

Theoretically, you could randomize all words in every Lorem Ipsum and it wouldn’t affect my ability to process UI mockups in the least. However, obviously, randomizing words in code snippets, or even just randomly swapping Foo’s and Bar’s, would be a terrible idea. Lorem Ipsums don’t have a structure (or, at least, we don’t care about their structure), but code snippets do.

All in all, I would say that Lorem Ipsum are true text placeholders and no one really cares about their contents. That’s not the case when Foo’s and Bar’s are used in code snippets, so I’m not even sure that the term “placeholder” is appropriate in this case.

Naming is Important

Imagine for a moment that you review your colleague’s pull (merge) request and come across a class named Foo which has a method named Bar. Would you let this code into production? Would your decision change if your colleague would claim that the names of this class and its method aren’t important?

I think most developers would righfully reject that pull request. The mental overhead of future readers of that code, who will pause over these names, makes them a poor choice. In fact, just the mental overhead of a single code reviewer makes it a bad idea to begin with.

Here is an interesting question: if most developers wouldn’t allow Foo’s and Bar’s in a codebase because they might puzzle a small number of potential future readers, why do we allow them in software documentation which is intended for mass consumption? I honestly don’t have an answer to this quesion, not even a speculative one, so feel free to share your opinion in the comments.

Someone could say that Foo’s and Bar’s in docs are not as bad as in real projects because code snippets in docs usually don’t have broader context. This might be true, but, in my opinion, this argument makes Foo’s and Bar’s even less suitable for documentation purposes. The problem is that these names do look contextual, so my brain automatically attempts to infer contexts from them and I need to make a consious effort to block these attempts. If you want to avoid any context in docs, names like A, B, C, or Class1, method2(), var3 would be much, much better choice.

Use Meaningful, Real-World Examples in Docs

If not Foo’s and Bar’s, then what? I think that using meaningful, real-world examples is the best course of action. Let’s review each of these points.

Meaningful examples are much easier to process and they can make the readers understand the intent better.

For example, this code snippet makes no sense and, even though I wrote it, I still can’t process it effortlessly:

public class Foo {
    
    private final Bar bar;

    public Foo(Bar bar) {
        this.bar = bar;
    }
    
    public void baz() {
        bar.bak();
        ...
    }
}

Now consider this alternative:

public class Client {

    private final Service service;

    public Client(Service service) {
        this.service = service;
    }

    public void execute() {
        service.executeFirstStep();
        ...
    }
}

The above example leverages the standard client-service terminology, which makes the relationship between classes very clear. I don’t even need to read it, to be honest, because my brain works in some kind of pattern-recognition mode and the eyes immediately jump to the relevant parts of code.

There is a caveat, though: in many languages and framework, common terms like “client” and “service” can have very specific meanings. If that’s the case, then you might want to be more careful with them (which isn’t the same as saying that you can’t use these terms at all). However, we’re not back to Foo’s and Bar’s because there are many other meaningful alternatives.

For example:

public class UsersManager {

    private final UsersDatabase usersDb;

    public UsersManager(UsersDatabase usersDb) {
        this.usersDb = usersDb;
    }

    public void clearUsers() {
        usersDb.clear();
        ...
    }
}

This code, even though a bit more specific, is still simple to understand and actually makes sense.

Now let’s discuss the “real-world” aspect of software documentation. What I mean by this is that you should choose examples that future readers could theoretically encounter in a real-world codebase. Note the “codebase” part because it’s important.

The fact that there is something called “thermosiphon” in the real world doesn’t make it a good example to use in software documentation. The fact that dogs bark and cats meawou isn’t helpful in understanding complex technical topics either. Don’t try to be original or entertaining with your examples, that’s not what readers look for in docs.

In my opinion, you ultimate goal with examples in software documentation should be for readers to think: “I can see how I could fit this exact code in a real project”.

Newcomers Friendly Examples

Some people seem to worry that if they’ll use meaningful, real-world examples, then their docs will become more challenging for new developers. Let me share my opinion on this concern.

First of all, I think there is a place for “dog and cat extend animal” examples. If you write a blog post or a book on OOP (or any other fundamental topic) for completely new developers, it makes sense to start with intuitive explanations. Even if these explanations will be a bit artificial from real-world software point of view. However, even introductory books shouldn’t culminate in “dog is an animal” or “a car has an engine” because it would leave the readers awfully unprepared for real software development.

That said, in my opinion, the above discussion is irrelevant to software documentation because it shouldn’t aim to teach the basics of software development. There are other, much better resources for that. Furthermore, chances are that developers who read docs are long past the “dog is an animal” stage anyway.

In addition, there are many examples which can leverage the general pre-existing “consumer” intuition. Stuff like userManager.login(username, password) or cart.add(product) will be intuitively clear to anyone who shops online, while also being sufficiently representative of real-world software.

All in all, in my opinion, concerns about software documentation not being “newcomers friendly” are unfounded in most cases. Even when they are valid, using Foo’s and Bar’s won’t improve the situation, on the contrary. Therefore, much of this dicussion sounds like underestimation of other people to me.

Conclusion

In software development, we often say that we spend ten times more time reading code than writing it. With software documentation, the ratio between reading and writing can be much higher than that. Therefore, if you really want your software to be succesful and you want its users to be happy, invest effort and thought into docs.

In this post, I shared my opinion on the practice of using meaningless terms in software documentation. I realize that most of the above points are my subjective judgements, so take them with a grain of salt. That said, as a blogger and an author of online courses, I spend A LOT of time thinking about proper naming. All my experience screams that Foo’s and Bar’s should be avoided like a plague.

As usual, thanks for reading and leave your comments below.