The Art of Readable Code

Chapter 3. Names That Can’t Be Misconstrued

In the previous chapter, we covered how to put a lot of information into your names. In this chapter, we focus on a different topic: watching out for names that can be misunderstood.

Key Idea

Actively scrutinize your names by asking yourself, “What other meanings could someone interpret from this name?”

Really try to be creative here, actively seeking “wrong interpretations.” This step will help you spot those ambiguous names so you can change them.

For the examples in this chapter, we’re going to “think aloud” as we discuss the misinterpretations of each name we see, and then pick better names.

Example: Filter()

Suppose you’re writing code to manipulate a set of database results:

results = Database.all_objects.filter("year <= 2011")

What does results now contain?

• Objects whose year is <= 2011?

• Objects whose year is not <= 2011?

The problem is that filter is an ambiguous word. It’s unclear whether it means “to pick out” or “to get rid of.” It’s best to avoid the name filter because it’s so easily misconstrued.

If you want “to pick out,” a better name is select(). If you want “to get rid of,” a better name is exclude().

Example: Clip(text, length)

Suppose you have a function that clips the contents of a paragraph:

# Cuts off the end of the text, and appends "..."
def Clip(text, length):
    ...

There are two ways you can imagine how Clip() behaves:

• It removes ...