On Meaningful Names

On Meaningful Names

by Kenny Porterfield | Thu, Jul 1 2021

Category: JavaScript

Meaningful Names

Names are everywhere in code. We name variables, functions arguments, classes, packages, source files, directories, etc. We name and name and name. Because we do it so much, it's important to do it well. Here are some tips that I've come across on coming up with meaningful names.

 

Intention Revealing Names

The name of a variable, function, or whatever, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent.

 

Avoid Disinformation

Avoid leaving false clues that obscure the meaning of code. Something like referring to a group of accounts as accountList unless it's actual a List because the word list has a specific meaning in programming. Call it accountGroup or just accounts instead.
Beware of using names which vary in small ways. It should be easy to spot differences between names. Spelling similar concepts similarly is information. Using inconsistent spellings is disinformations. It is very helpful if names for similar things sort together alphabetically and the differences are obvious.

 

Make Meaningful Distinctions

Distinguish names in such a way that the reader knows what the differences are. Avoid noise words, or anything redundant. The word variable should never appear in a variable name, the word table should never appear in a table name.

 

Use Pronounceable Names

Think of programming as a social activity. You'll need to be able to discuss your code with other developers. Make your names pronounceable. If you can't pronounce it, you can't discuss it well.

 

Use Searchable Names

If a variable or constant might be seen or used in multiple places in a body of code, it is imperative that it has a search-friendly name. Single letter names are not easily located by searching, and should only be used as local variables inside short methods. The length of a name should correspond to the size of its scope.

 

Avoid Mental Mapping

Avoid naming something that you mentally translate into other names because it seems to make sense to you. You might be smart and what you're doing makes total sense to you, but there's a difference between being a smart programmer and a professional one. A professional understands that clarity is king, and writes code that others can understand.

 

Class and Method Names

Classes and objects should have noun or noun phrase names. A class name should not be a verb.
Methods should have verb or verb phrase names.

 

Don't Be Cute

Will people know what the function named HolyHandGrenade is supposed to do? Possibly, but maybe in this case DeleteItems would be better. Choose clarity over entertainment value.

 

Pick One Word per Concept

Pick one word for an abstract concept and stick with it. For example, it can be confusing and is often unnecessary to have fetchretrieve, and get as equivalent methods of different classes. A consistent lexicon is a great advantage to the programmers who must use your code.

 

Avoid "Puns"

Using the same term for two different ideas is essentially a pun. Avoid using the same word for different purposes. For example, say you have an add method on multiple classes. As long as add means the same thing, that's fine, for example if add literally means adding numbers together. But, if you need to also "add" a value to an array or something like that, you'd want to name it something different, like append or insert, because it has different meaning. The goal is to make code as easy as possible to understand, and one word having multiple meanings makes understanding what that word means more difficult.

 

Don't Add Gratuitous Context

Shorter names are gnerally better than longer ones, so long as they are clear. Add no more context to a name than is necessary.



Check out other JavaScript blogs.

Comments

Login or create an account to leave a comment.

Recent Blog Posts

Get in touch

Kenny Porterfield
kjport3@gmail.com
LinkedIn

Or, send me a message from here: