Tom MacWright

Picking better names for variables, functions, and projects

Naming things in programming is hard. It’s not impossible, though. Here are some guidelines I usually follow.

Avoid weasel words

Wikipedia’s article about weasel words is incredible. In this context I mean words like this:

  • Data
  • Process
  • Run
  • Do
  • Setup

These words usually don’t mean anything at all. Any variable could be called data. Any method could be called process. These words don’t inform or differentiate. Most methods and variables that include these names are misnamed. Think hard and figure out what’s better:

  • A method like processData probably isn’t processing any kind of data. Maybe processCsv?
  • Is it really just “processing” that CSV. Maybe it’s coercing columns that are strings that should be numbers. Maybe coerceCsvRows?

That’s probably better!

  • A variable like data probably isn’t generic data. Maybe it’s… recentPosts?

Follow patterns religiously

Let’s say that you have a bunch of types describing database associations. Commentable, Archivable, etc. Strictly, dispositional adjectives. Follow this pattern for the rest of those types, even if there are awkward cases.

It’s usually better to have awkward cases than to have exceptions to the rule. Observe XMLHttpRequest for example - a name that follows neither camelcase-without-acronyms (XmlHttpRequest) nor acronym-preserving camelcase (XMLHTTPRequest). Stick to one!

Don’t cheap out on characters

Needless abbreviations are a more subtle form of single-letter variable names. If something is a document, call it a document, not a doc. Only in extreme cases - referring to internationalization as i18n is any sort of truncation appropriate.

Call things the same thing

If you have a variable called rows and you pass it to a method that works with row data, the parameter to that method should probably be called rows as well. Unless there’s a reason to use a different name for the same kind or instance of data, don’t use different names for it, use the same name.

Similarly, don’t needlessly reassign variables. An assignment like let theData = input doesn’t add clarity or serve a purpose. Reassign if the type or value of input changes and deserves a different name.

Don’t name internal projects

In the macro sense: don’t name the parts of your infrastructure after planets in Star Wars or Russian words for blue or different kinds of birds. Just name them what they do. Clever naming for internal projects trades a little fun now for endless annoyance onboarding people to non-descriptively-named projects. If the thing is a microservice that sends mail, call it mail-service and be done with it - spend that energy choosing a really good name for a dog. If you want the name to be a little more unique on your filesystem or GitHub, add a prefix - mycorp-mail-service.

When things change, change their names

Naming drift is a constant problem: a method that was called sendMail and sent mail was refactored to just format mail and pass it on to another method that actually sends the mail. When you refactor code, rename your methods.

Similarly, when you’re writing code at all, just stare at what it does and what it’s called and make sure that they are the same thing. If the method is called renderPage but it really just sets up the datastructures to render the page, call it something else.

When naming is strong, you rely on names. You can look at a method name and guess what it does. Choosing decent names is time well-spent.

You might have seen this post as a gist I posted to Twitter. I’m making an effort to move some things I’ve written from other sites onto this one for posterity.

February 17, 2021  @tmcw