The Art of Readable Code

Chapter 2. Packing Information into Names

Whether you’re naming a variable, a function, or a class, a lot of the same principles apply. We like to think of a name as a tiny comment. Even though there isn’t much room, you can convey a lot of information by choosing a good name.

Key Idea

Pack information into your names.

A lot of the names we see in programs are vague, like tmp. Even words that may seem reasonable, such as size or get, don’t pack much information. This chapter shows you how to pick names that do.

This chapter is organized into six specific topics:

• Choosing specific words

• Avoiding generic names (or knowing when to use them)

• Using concrete names instead of abstract names

• Attaching extra information to a name, by using a suffix or prefix

• Deciding how long a name should be

• Using name formatting to pack extra information

Choose Specific Words

Part of “packing information into names” is choosing words that are very specific and avoiding “empty” words.

For example, the word “get” is very unspecific, as in this example:

def GetPage(url):
    ...

The word “get” doesn’t really say much. Does this method get a page from a local cache, from a database, or from the Internet? If it’s from the Internet, a more specific name might be FetchPage() or DownloadPage().

Here’s an example of a BinaryTree class:

class BinaryTree {
    int Size();
    ...
};

What would you expect the Size() method to return? The height ...