Meaningful Names

Names are everywhere in software. We name our variables, our functions, our arguments, classes, packages, source files, directories, ... What follows are some simple rules for creating good names.

Use intention-revealing names

The name of a variable, function, or class, 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.

What does the list represent?

Avoid disinformation

Programmers must avoid leaving false clues that obscure the meaning of code. We should avoid words whose entrenched meanings vary from our intended meaning.

Of what type is the account list? String? Array of strings? Array of objects?

The lower-case L or uppercase O ? or they look almost entirely like the constants one and zero, respectively.

Avoid similar shapes

How long does it take to spot the subtle difference?

Make meaningful distinctions

How do these different names convey different meanings?

Use pronounceable names

How can you discuss it without sounding like an idiot?

Use Searchable Names

Single-letter names and numeric constants have a particular problem in that they are not easy to locate across a body of text.

What is the number 34 , 4 or 5?

Avoid Encodings

It hardly seems reasonable to require each new employee to learn yet another encoding “language” in addition to learning the (usually considerable) body of code that they’ll be working in.

Member Prefixes

Don’t need to prefix member variables with m_ anymore. Your classes and functions should be small enough that you don’t need them.

Interfaces and Implementations

or

I don’t want my users knowing that I’m handing them an interface. I just want them to know that it’s a ShapeFactory. So if I must encode either the interface or the implementation, I choose the implementation.

Avoid Mental Mapping

This is a problem with single-letter variable names. Certainly, a loop counter may be named i or j or k (though never l!) if its scope is very small and no other names can conflict with it. This is because those single-letter names for loop counters are traditional. However, in most other contexts a single-letter name is a poor choice.

Class Names

Classes and objects should have noun or noun phrase names.

Avoid words (in the name of a class)

The class name means the class does more than one thing. It doesn't say anything specific

Method Names

Methods should have verb or verb phrase names like postPayment, deletePage, or save. Accessors, mutators, and predicates should be named for their value and prefixed with get, set, and is according to the JavaBean standard.

Prefer methods to constructors overloaded

When constructors are overloaded, use static factory methods or builders with names that describe the arguments.

Adjust the length of a name to the size of its scope

Is it obvious outside the class body that WD is an acronym for work days per week?

If a variable or constant might be seen or used in multiple places in a body of code, it is imperative to give it a search-friendly and meaningful name.

Avoid using the same name for different purposes

What does add mean? Concate strings? Insert a record in a table? Append a value to the end of an array?

Use Solution Domain Names

Remember that the people who read your code will be programmers. So go ahead and use computer science (CS) terms, algorithm names, pattern names, math terms, and so forth.

The name AccountVisitor means a great deal to a programmer who is familiar with the Visitor Pattern.

Use problem domain names

What does the term "document" mean in the archives domain? Are photos considered documents?

Add Meaningful Context

There are a few names which are meaningful in and of themselves—most are not. Instead, you need to place names in context for your reader by enclosing them in well-named classes, functions, or namespaces. When all else fails, then prefixing the name may be necessary as a last resort.

What does a comma , mean? How to change all of them for a specific context?

Don’t Add Gratuitous Context

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

Add context by using prefixes

What does the state represent? Condition or country?

The names accountAddress and customerAddress are fine names for instances of the class Address, but could be poor names for classes.

If you need to differentiate between MAC addresses, port addresses, and Web addresses, consider PostalAddress, MAC, and URI.

Last updated