Skip to Main Content
The Art of Readable Code
book

The Art of Readable Code

by Dustin Boswell, Trevor Foucher
November 2011
Intermediate to advanced content levelIntermediate to advanced
206 pages
4h 32m
English
O'Reilly Media, Inc.
Content preview from The Art of Readable Code

Chapter 3. Names That Can’t Be Misconstrued

image with no caption

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 ...

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.
Start your free trial

You might also like

Five Lines of Code

Five Lines of Code

Christian Clausen
The Art of Clean Code

The Art of Clean Code

Christian Mayer

Publisher Resources

ISBN: 9781449318482Errata Page