Naming

naming.md

Naming things in programming is pretty 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 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 shortening 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.

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.

A few additions:

Run

Yes, except when the "weasel words" are the names of methods, and the actual name is the name of the class.

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.

It works, except sometimes it doesn't. If the software is about doing something with Docker and itself runs on Docker, then there is an ambiguity, and one of the names will have to change.

It works, except sometimes it doesn't. If the software is about doing something with Docker and itself runs on Docker, then there is an ambiguity, and one of the names will have to change.

I would suggest using some kind of specific prefix/salt to work around this uniqueness issue. Something like foo-mail-service where foo is a shorthand for the product or the company.

Can I make PRs for gists?

I'd like to add this to Call things the same thing:

Likewise, when iterating over `rows`, each item should be called `row`.

I think there should some exceptions for short names, as they pose less cognitive burden to process and make the code shorter. The exception should be made as long as the name chosen is still readable, non-ambiguous in its scope, and doesn't have a common prefix with another name in a local scope.

I'll expand about common prefixes - for example, car_item_value and car_item_key having the same prefix, both being used and declared in the same space, may add mental burden on the reader. If they are of the same type in the language, then it's even worse, because they can be confused with each other during editing or reviewing. For this example, renaming them to key_car_item, and value_car_item may be an improvement. I take the 'avoid common prefixes' to heart in such manner that I seek names that don't even share the first letter, so that my mind can minimize the time it takes to differentiate between the identifiers.