[Better Developers #3] How to name things

Better Developers
Issue #3 · Full archive

How to name things

A well-known saying among programmers, attributed to Phil Karlton, is that there are only two hard things in computer science: Cache invalidation and naming things. I'm no expert at cache invalidation, and thus can't speak to it. But like most developers, I'm constantly naming things — files, functions, modules, classes, and methods — and I'm thus always coming up with new names. And naming things can indeed be hard, especially if you consider that the names we give affect not only us, but the people who will be maintaining our software in the future.

While naming things might be hard, it's an important action that developers do every day. Good names can help you to focus on the right things in your code, whereas bad names can encourage you to concentrate on the wrong things — and even worse, can make your code hard to maintain, by yourself and others.

So, how can (should) you name things in your programs?

Name from the user’s perspective

The first thing is that you should give names based on the user's perspective, rather than the software's perspective. It's so easy to get wrapped up in our software architecture, deciding which part connects to which, that we can forget that we're designing the software to solve people's problems. Using terms that have to do with our users helps us to understand their needs better, and to address their problems more quickly.

Having this perspective can also help to avoid problems. For example, I work with a home-rental company that started in one location and expanded to many others. I figured out how to handle each new location via a separate domain within a single application; this is called a "multitenant" application. I thus created a tenant object, with each tenant representing a single location at which our company worked.

Oops. Had I thought about my users, rather than the software, I would have quickly realized that using the term tenant at a rental company would cause problems. And indeed, it has caused problems. But it's too late now; the term tenant for a location has stuck, and the software is full of uses of tenant that make sense to developers, but not so much to people.

Once you think about your users and their needs, you can also start to think about how to give simple names to the things you're creating. It might take a few tries to come up with something good, but simple words are often the best. And while it might not be obvious, remember that functions should be verbs and objects should be nouns. My general rule is for class names to be singular nouns, too. That way, you can say:

friend = Person('John', 'Smith')

Notice that in the above example, I put the new instance of Person inside of a variable named friend. That's on purpose; while I will sometimes be lazy and say p1 or p2, my inclination is always to use a real word, rather than i or x. Indeed, I think that I'm the only programmer I know who basically never uses i as a loop variable. I'd rather use index or "counter" or something else that's less ambiguous.

Write names you can read out loud

Moreover, I like my code to be readable — not just in the sense that it should be easy to read, but also that it should make sense when read out loud. For example, if I'm asking the user to choose from a menu, I might say:

user_choice = input("Enter a or b: ")

Why? So that my next line of code can be:

if user_choice == 'a':
    print("Thanks for choosing 'a'")

This allows me to read my code out loud, as "if user_choice equals a..." Perhaps it's just because I talk on the phone with many of my clients, or spend much of my time teaching, but the ability to read code out loud and have it make sense (or come close to making sense) is important.

This is why I name many of my boolean variables is_xxxx. This allows me to say things like:

if user.is_logged_in:
    do_something()

As you can probably tell, I also like long names. Maybe it's because I learned to program in Lisp (famous for long variable names), maybe it's because I type quickly, and maybe because I'm a verbose kind of guy. But I'd much rather have a variable called daily_rainfall than d or r.

Remember that the language you're using doesn't care about the names you give to your variables and functions, but the programmers who will be using your system will.

I'm not sure whether this is still popular, but there was a trend for years called "Hungarian notation" — named for Charles Simonyi, a Hungarian-born programmer who worked at Xerox PARC and then at Microsoft. The basic idea of Hungarian notation is that the type of variable you're using is indicated as part of the variable name itself. So lTaxBill, prefaced with the letter l, would be a long integer. There were all sorts of prefixes, and I'm sure that there was some benefit to this system, but I always found it to be far too confusing and not worth the time.

Names are for whoever maintains the code

Finally, and perhaps most importantly, consider the issue of names when you next have to maintain some code. If it's hard for you to understand at first glance, think about what changes you would make (if you could) that would make the code smoother and more obvious. True, there will probably be some algorithmic improvements, but I'm talking here about the names used: Which function names are non-obvious? Which parameter names could be improved?

Over time, you'll develop your own style, but also an internal sense of how to name things so that your code becomes easier for others to read. And of course, easier for yourself to read, as well.

Do you have any naming conventions that help you (or your team) to write more maintainable code? I'd love to hear about them; just reply to this message, and tell me what you think.

Until next week,

Reuven