Names are everywhere in codes. Write them right. Don't be afraid to change names into something better. Coders often search and index names, not memorize them, so it's often easier to deal with name changes than expected.
Good naming requires good descriptive skills and a shared cultural background. This is focused around teaching skills, not technical skills, so it's often tough for programmers to do right.
Reveal Intention with Names #
A name should quickly convey the following threee points of meaning. If the name needs a comment, it's not doing this right.
- Why it Exists
- What it Does
- How it's Used
The more a name requires extra context or explanation, the less intention it reveals.
Avoid Disinformation #
Avoid words whose entrenched/common meaning differs from the intended meaning. This happens a lot in long code names with subtle differences. Using tools for automatic code completion helps avoid this.
An example is the name
hp when it could be confused with the company HP, or an acronym for hypotenuse, or others.
Another is using the letter
l as a var name, since it could be confused with the integer
Make Meaningful Distinctions #
Don't change identical names by making arbitrary changes between them, such as:
- Deliberate mispellings (
- Number series (
- Noise words (
- They don't make them mean anything different, are redundant
- Prefixes like
thework as long as they're meaningful, like
afor local variables or
thefor function arguments.
Use Pronouncable Names #
You need to talk about code with others. If you can't pronounce it, you sound like an idiot talking about it.
Use Searchable Names #
Single letter or numerical constant names are tough to locate across bodies of text. For example,
e is a bad name since the letter appears basically everywhere.
Long names trump shorter names. The name length should correspond to the scope size. If used in multiple places or in a larger scope, make sure the name is larger and more searchable.
Avoid Encodings #
Don't encode data types or scope into names (
block, etc). It's just an extra burden of info to figure out.
Implementations, not Interfaces #
If using a pattern or interface, like the
factory pattern, don't denote it as an interface with a name like
ShapeFactory is clearer, focusing on the implementation over the interface.
Programmers are going to be the ones reading your code, so don't be afraid to use computer science terms like
visitor in names like
Avoid Mental Mapping #
Readers shouldn't need to mentally translate names into others they already know. Don't create an extra bridge between the name and what it means. Clarity is king in bridging that gap for the reader.
Class and Method Names #
Classes and Objects use noun or noun-phrases, like
Methods should have verbs or verb-phrases, like
Method Prefixes #
- Accessors =
- Mutators =
- Predicates =
Don't be Cute #
Funny or clever names only make sense to whoever's in on the joke. Clarity beats entertainment value, especially culture-dependent jokes.
One Word per Concept #
Pick and stick with one word per abstract concept and stick with it. If you use
get throughout the code, just pick one and use it everywhere.
Don't Pun #
Never use the same word for two purposes, which is basically a pun. The word
add should only mean one kind of
Add Meaningful Context #
Some names on their own aren't meaningful. Enclosing them in well-named classes, functions, or namespaces adds the needed meaning. Prefixing the name is a last resort.
For example, several names like
city can get meaningful context as part of a class named
Address. If you can't do this for some reason, prefixes like
addrFirstName will work despite not being as good.
On the flipside, some context isn't needed. An application names
BudgetSaverHelper doesn't need to add the
BSH prefix to each class. It only makes names harder to search since
BSH searches return everything.
personalBudget are good instance names, but have gratuitous context for class names. Just
Budget would work fine. The name can then be specified if multiple types of budget classes are needed.