How to write maintainable code: Naming things

Using the right names is an essential part of writing maintainable code. For a computer, any name will work just fine—they either match or not. For the humans who read the code, the names are the first thing they have in mind as they work on the code. We all have some capacity to deal with a wrong name. If necessary, we can do a mental translation when the name doesn’t match the concept, or we can ignore some typo. But doing so uses both our memory and mental capacities. It’s easier and more efficient to work with the code that has the naming done right.

One name for one thing

For organizing our stuff, the general advice is to have a place for everything and everything in its place. Similarly, our lives will be much easier if all the people involved in the same project use the same terminology. Usually, we developers don’t have a perfect understanding of the domain in which the project is used. As a result, it makes the most sense to learn the terminology that is used by our business colleagues and use it in the code as well.

Parts of speech

To create terminology that is easy to use, it makes sense to apply some of the grammatical knowledge we all got from school. Different types of words fit better in different use cases:

• nouns are a perfect fit for objects or primitive values: user, accountNumber, customerEmail
• adjectives work great for some Boolean flags: allowed, disabled
• verbs match functions or object methods user.login(), shutDown()

You’ll likely find cases where it would make sense to bend this rule, but for me, it makes sense to try tweaking the names to match this pattern. For example, for a method that checks the current state, I would use user.isActive() instead of user.active().

Avoid abbreviation

I’m always skeptical of abbreviations as names in code. Many abbreviations are obvious only when you are deep in the context of the code. A reader who is new to the code and the domain can be confused. Making names short doesn’t improve meaningful metrics. When we write code, we usually use code suggestions, and most lines fit on the screen anyway.

When there is potential conflict between brevity and clarity, I always prefer to stay on the side of clarity. The only abbreviation I can think of now that I’m OK with seeing in code is VAT. It’s so commonly used that it is easier to understand than its expanded form: value added tax.

Pronunciation

All names we put to code are used in two ways. In writing—in code or documentation, and in speech—and when we talk about them. It’s important to think about both use cases when choosing the name. Pronunciation is often another reason to avoid abbreviations: they often miss vowels, and you may need to say it letter by letter.

Avoid name collisions

Try not to reuse the names with different meanings in other contexts. If you use some synonyms instead, then it will be easier for developers to intuitively understand the terms correctly when they hear it—without overthinking about the context in which they were used.

Brainstorm ideas

I have a high bar for naming things. Some names are easy to create; others are more difficult to come up with. For the most complicated cases, I try to write down as many ideas as I have in the ticket that will introduce a given concept to the code. I try to generate about 3 to 5 ideas—if it’s very difficult, I write down even the ones I don't like. With this in place, I ask my colleagues for their opinion. In this way, I get an external input and spend more time on thinking about the name. It helps in making the decision.

Newsletter

If you want to get occasional emails about programming or related topics, you can sign up for my newsletter here.