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:
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
processDataprobably isn’t processing any kind of data. Maybe
- Is it really just “processing” that CSV. Maybe it’s coercing columns that are strings that should be numbers. Maybe
That’s probably better!
- A variable like
dataprobably isn’t generic data. Maybe it’s…
Follow patterns religiously
Let’s say that you have a bunch of types describing database associations.
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 -
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.