Think of all the times you name things while developing software. You name variables, functions, classes, files, directories, modules, commits to your version control system, deliverables, versions, bug tickets, etc.

You name things all the time. But are you good at naming?

Naming things is hard. When we want to do it right, when we want to find great names, it’s one of the hardest things to do.

And naming things is important. A good name can make the code more readable and maintainable. A good name can explain why the code is like that to the next person. A bad name can make it harder to write the next feature. It can be the reason for a future bug.

However, many programmers I know—far too many—name things carelessly. They do not think nearly enough about the names they create.

So, how should we name things? What makes a good name? What makes a bad name?

This example on the left misses the fact that there is some validation happening. We can do better by encapsulating the validation in a domain class. In the example on the right, the validation happened long before payTaxes is called:

public void payTaxes(String taxAccountNo,
            int amountInCents)
            throws TaxAccountNumberExc {
    validate(taxAccountNo);
    /* ... */
}
	

public void payTaxes(
        TaxAccountNumber taxAccountNo,
        MonetaryAmount amount) {
    /* ... */
}
	

If your name is too long, what you are trying to name is too big. See this as a refactoring opportunity.

Names should be on a slightly higher level of abstraction than what they name.

A name that describes what the variable/method/class is doing does not create a higher-level concept and does not help us to understand the software better. But when the name is too abstract, too disconnected from what it is naming, it will also create confusion.

The name you choose should help the reader understand what happens in the code. It should also help them to understand why the code is the way it is.

for(int i=0; …) {
for(int row=0; …) {
for(int searchRow=0; …) {
	

1. The code seems to do something with indexes.
2. The code iterates over rows, probably in a list or a table.
3. The code searches for something in row data, probably a list or a table.

If a businessperson can understand the name, you are probably on the right path. Compare these two names:

boolean isDefault;
boolean isPreferredShippingAddress;
	

Do not use abbreviations (except for very well-known abbreviations from your business domain). Sometimes “i” is appropriate for an index, but most of the time, you can come up with a better name.

When you have multi-part calculations or Boolean expressions, extract the parts to variables or functions. Then you can give them a meaningful name:

boolean hasOrders = orders != null && !orders.isEmpty();
boolean booksOrdered = hasOrders && orders.stream().anyMatch(x -> x.isBook());
boolean magazinesOrdered = hasOrders && orders.stream().anyMatch(x -> x.isMagazine()); 

if(booksOrdered || magazinesOrdered) { … } 
	

We could have written all these checks inside the “if” condition, but naming all the intermediate results is more readable. It reveals our intent and informs the reader of the business concept behind the expression.

In relation to that, you should even name the small things. A calculation is never too small to be extracted to a local variable. Code is never too small to be extracted to a method. But beware of adding too much indirection. When it becomes hard to find the place that actually does the work because of all the abstractions and delegations involved, then you went too far.

These are just a few guidelines for finding proper names. When it comes to naming, do not forget the overall goal. By choosing good names, you are making the code more readable and more maintainable. You are showing the next person not only what the code does, but also why it is there and how it connects to the business domain.

You are trying to reduce the cognitive load of a future reader by hiding some details. When someone reads the name of a class or a method call, they should not be required to also read the content. They should know everything they need at that point from the name.

When choosing names, you want to help future readers and future maintainers. And that person might even be your future self, so take extra care when you are naming things!