There are often many words with similar meanings you could choose when naming a variable. This section gives guidance on effectively choosing words.

Avoid Words That Could Be Confused for Too Many Different Things

As previously discussed when talking about name specificity, one of the problems with overly generic names is that they could be used for multiple purposes - the variable could represent more than one thing, and a reader would be left guessing (potentially incorrectly) as to what the variable actually represents. Such confusion inhibits understanding and correct maintenance of code.

Similarly, there are some words that could mean too many different things and are best avoided in most scenarios. One of the most common words in this category is “number”:

Avoid “Number” in Favor of Alternatives [VC1]

For example, would employee_number refer to a “total number of employees,” an “employee ID,” or an “index into an array of employees”? It’s not evident from the name itself, and all three of these concepts could easily occur in the same context of code. Therefore, a name like employee_number is prone to mix-ups.

Depending on what you’re representing, there are several alternative terms that tend to work better:

• count - Represents something like a “total number” as if you were counting items one-by-one. So with an employee_count of 10, one would know that there were 10 different employees counted. If the “count” is a total number of employees, then an additional word can be added for clarity: employee_total_count. When using count as a suffix, that inherently implies the potential for a “plural” number of things. Plurals in the middle of variable names tend to be harder to read (ex. employees_count), so singular terminology is often better to use in these kinds of count variable names.

• id - Represents something that would act as a “unique ID” for something. So employee_id would be some way to identify an employee within a system (exactly what kind of value the ID is - a number, string, etc. - would be dependent on the system). If additional clarity is needed, then a name like employee_unique_id can help.

• index - Used for indexing into collections like arrays. So an employee_index of 0 would indicate the numeric index for accessing the first item of an array (in a programming language with 0-based array indices). One thing to be aware of with index terminology, however, is that it can sometimes be used to refer to a “search index” in computing. Be aware of context and add additional specificity if needed.

The following code example shows how these different terms can come into play:

“Number” may be fine to use in comments as a way to provide additional human clarity as to the meaning of variables using terminology above. But it’s best avoided in actual code.

An exception to avoiding “number” is if you are dealing with a very specific problem or technical term where “number” is the accurate terminology. For example, if working with a phone number or social security number, variables names like phone_number or social_security_number would be very appropriate. Inventing new terminology could cause confusion.

Remember Common Opposites

Keep common opposites in mind, and aim for consistency in cases where alternative terms aren’t definitively better.

Some common opposite pair words include:

• add/delete

• add/remove

• begin/end

• connect/disconnect

• earliest/latest

• expand/collapse

• first/last

• horizontal/vertical

• increase/decrease

• increment/decrement

• left/right

• lock/unlock

• min/max

• old/new

• open/close

• previous/next

• read/write

• send/receive

• start/stop

• source/destination

• source/target

• top/bottom

• up/down

• visible/invisible