Good names

Code is full of identifiers. Whether that’s variables, functions or types. If you’re doing something to something else chances are that one or both of those involve identifiers. I not going talk about how you format a name for the moment, whether you use camel case, snake case or something else. This is about the letters or words you choose and how it affects the code you produce.

Some people take a minimalist approach, like a mathematician might use when jotting down equations. Some people take a maximalist approach, ensuring each identifier tells use it’s full purpose and use. Many people lie somewhere in the middle.

An ideal identifier should:

• Be quick to type.
• Be quick to read.
• Let you fit enough on a line.
• Be meaningful so the reader understands it’s use.
• Convey a grouping between related identifiers.
• Be distinguishable from similar identifiers.
• Be searchable so it can be found within the project.
• Be helpful for those unfamiliar with the code.
• Be easy for those familiar with the code.

It seems that the ideal identifier would be both short and long, similar and dis-similar to others, optimised for beginners and experts. Some of the time an ideal identifier just doesn’t exist.

My guidelines

While all the criteria for an ideal identifier are valid but I don’t think they’re equal:

• Identifier are read more than they are written.
• Good identifiers should be understood by everyone, familiar or unfamiliar.

Given all that I use these guidelines when choosing most identifiers:

• Use one or more words.
• Use a short meaningful name given the current context.
• Similar concepts should be named in a consistent way.
• Well know contractions are okay, e.g. max or html, but avoid non-standard abbreviations or acronyms.

My reasoning for word based identifiers is that they are:

• More easily meaningful to a reader, even if they’re unfamiliar.
• More consistent across the codebase to make them familiar and searchable.
• Have more letters to provide similarities or differences as required.
• Don’t slow things down too much.
• Don’t take up too much space.

I have a special exceptions allowing for single letter identifiers:

• i, j and k for-loops.
• x, y and z for positions.
• Any letter for identifiers declared and used on one line.

My reasoning for these exceptions are:

• Some single letter identifiers are very familiar. (Don’t go beyond k which is already pushing it.)
• Single line declarations need to be short and should be simple because they are short.

Some example variables:

• user, count, file
• externalTemperature, errorText
• maxStoppingDistance

Some examples functions:

• Parse, Send, Count
• OpenFile, RemoveDuplicates

Some example types:

• Configuration, Range, Error
• JsonFile, SqlDatabase

Abbreviations and acronyms

Abbreviations in code normally doesn’t save that much and makes the code unnecessarily confusing.

I’ve seen fname and funname being used together. What do they mean? With the source code you could find the original declarations but wouldn’t using filename and functionName be easier? In particular, using an abbreviation that could be equally valid for more than one identifier is a bad idea.

I’ve seen configuration state being associated with identifiers: c, cn, conf, config and configuration. Standardising it would have made it easier to update code across the project. This is a situation where I’d accept config as a standard and shorter alternative name.

In most situations it’s the full word that has the great benefits of being standard and completely distinguishable. If you think an identifier is too long is there an alternate shorter word? If not, it’s better to have one abbreviation used across the whole project that can’t be confused with anything else.

Acronyms are more likely to save a lot of space but it can be impossible to guess their meaning. Typically this isn’t because the developer is inventing their own but using ones from a particular field. For someone familiar with the field this is fine, for anyone else it’s not. This could be someone new to the team, someone looking at source on a public repository, or even someone who hasn’t worked on this part of the project before. Unless everyone is going to understand your acronym a simple comment where it is first introduced helps a lot.

Code context

If your code is dealing with multiple concepts you can use compound words to draw attention to similarities and differences. So if you already have personName and personAge then using companyName is complementary. The Name suffix lets you know you’re working with the same type. The person prefix lets you know you’re working on the same thing. The additional company prefix lets you know what the other concept is.

If your code is only dealing with single concept at a then you can streamline the things. When dealing with just the person you can use name and age. When dealing with just the company you can use name. This could make it both easier and harder to search for things across the project. Searching for name will produce everything that matches but you have to spend looking for the right match. Sometimes when I could use a shorter form I stick with the longer form, e.g. personName, just to match the rest of the file.

Choose carefully

It can be worth trying to think through exactly what an identifier should be:

• Validate (check whether something follows a rule) or Verify (check whether something is true).
• Load (something into memory) or Read (something already in memory).
• Get (something we already have), Find (something within a single document) or Search (something within many documents).
• Get, Build (joining existing components together) or Calculate (combining or merging components).

There aren’t any concrete rules about these, you might disagree with my interpretation for these examples. It’s worth thinking about these choices rather than just picking the first thing that comes to mind. Use a thesaurus to help search for the best alternative.

For me finding the right name can just click as it matches exactly the concept in my head. If you have the right name code can be understood faster and is less likely to lead to bugs through misunderstandings.