Beginner’s guide for naming things in your code

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”

Martin Fowler, 2008.

Names, they are everywhere in our software. Just think of the things we name, we name our packages, classes, methods, variables, in fact us programmers do so much of it, we should probably know how to do it well.

In my opinion, making the code readable is just as important as making your code work.

In this post I will give you 5 tips and guidelines to choose your names in order to make your code more readable.

1. Reveal your intent:

The name you choose should answer as many questions as possible for the reader, questions like, why it exists, what it does, and how it is used.

Choosing good names takes time but saves more than it takes when the going gets tough, so take care with your names and change them when you find better names.

Let’s look at an Example:

int d; //elapsed time in days

Judging by the comment, it looks like d is some kind of integer that stores days.

Wouldn’t it be much better if d name would tell us what it’s used for:

int elapsedTimeInDays;
int daysSinceCreation;
int daysSinceModification;
int fileAgeInDays;

2. Choose the right parts of speech:

Classes and variables should have noun names like User, HtmlPage, Account, and AddressParser.

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

Avoid words like Manager, Processor, Data or Info, they usually don’t give much information.
If you are having trouble finding a name that describes what your class does, it may indicate design smell and maybe your class does more than one thing.

// Bad
interface DataManagerInterface {...}

// Good
interface EventsAggregator {...}

3. Avoid disinformation:

A misleading name can cause you and your fellow co-workers a lot of time and pain.

For example, do not refer to a grouping of accounts as an accountList unless it actually is a List.

If the container holding the accounts is actually a Set, it may lead to false conclusions.

// Bad
Set accountsList;
List accountsMap;

Don’t name classes as design patterns, unless they really are design patterns.

// This class is clearly not implementing the builder pattern
class ReqeustBuilder {
     public ReqeustBuilder(HttpServletRequest request) {...}
     public Request getRequest() {...}
}

Try to not use comments if you can express yourself in the code itself.

Comments tend to rot over time, because someone may change the code and keep the comment.

This can result in a misleading comment that may lead to incorrect assumptions.

4. The scope rule:

The length of your names should depend on the scope length where they are used.

For variables, use short names for short scopes and long descriptive names for long scopes.

Variables that are used within short scopes are usually defined very close to where they are used.

For instance, it is perfectly clear what e means here:

} catch (Exception e) {
    e.printStackTrace();
}

However, if the variable is used within a long scope, you don’t want your readers to go up 56 lines of code just to see that p means publisher.

Publisher p = Publisher.byName(data.getPublisherName());
/*
.
. // 56 lines of code where p is not mentioned
.
*/
if (p.shouldSendEvents()) {

For methods, it’s the other way around, use short names for public methods with large scopes:

public void open() {...}

And long names for private methods with small scope:

private void waitForServiceThreadToStart() {...}

5. Keep it simple

If names are too clever, they will be memorable only to you. Keeping the names simple and straightforward will do your code readability a favor.

Pick one word for one abstract concept and stick with it. For instance, it’s confusing to have fetch, retrieve, and get as equivalent methods of different classes.

Avoid encodings such as Hungarian Notation, our IDEs today are smart enough to make that notation redundant.

Wrapping up

Naming is a tool to communicate with your readers, bad names prevent code from clearly communicating its intent – so choose names thoughtfully and with care.

Other people, including your future self, need to understand the code to be able to make changes.

Nowadays, software maintenance provides the biggest day-to-day challenge.

Even if you are writing something totally new, maintaining is a task you, or your fellow co-workers, are definitely going to have to deal with, sooner or later.