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 fetch
, retrieve
, 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.