Picking good identifier names

Question

Ok, so you can read guidelines on identifier naming 'til you're blue in the face... camel case, pascal case, make 'em descriptive... but they won't help you actually pick the best name for a given application domain.

The easiest to choose (IMHO) are one or two word noun groups:

• EntryForm
• Employee
• WidgetCollection

But not every class fits neatly into a noun so I see a lot of people turn verbs into nouns by adding -er to the end of them:

• AccountManager
• RecordCounter
• ProcessRunner

The biggest problem I see with these is that a lot of time they're ambiguous... especially Manager. What exactly is it managing?

So my question is how do you pick a good name for a class? By 'good' I mean informative and unambiguous.

I know, I know. With refactoring support built into pretty much every modern IDE you can change the name without batting an eye so what's the point? Well a poorly chosen name will confuse and mislead anyone who stumbles across it until it's renamed so its still a valid question.

Related

What’s the best approach to naming classes?

Answer 1

Picking terse, informative, appropriate names for things is one of the hardest parts of programming.

There is no formula for it. It's a skill you pick up with experience.

Notice the emphasis on terse. The long names in Java is one of the major turnoffs of that language. It basically has gotten to the point that it's impossible to program in Java without an IDE with autocomplete.

Abbreviations can be your friend when naming. For instance, 'Mgr' instead of 'Manager'. Do I really need to type out 'Manager' a thousand times a day when 'Mgr' gets the point across? Just make sure people use them consistently and judiciously.

Answer 2

Clean Code is a good book but don't follow the advice on identifier names and comments. (See Self Describing Code and Long Identifiers Make Code Unreadable )

For example, here is Uncle Bob's bowling example (see other replies for Uncle Bob's code) done properly:

// Returns total score for a game of ten-pin bowling. On entry the number of fallen pins
// for each ball is provided in fallen[] and the number of balls bowled is in balls_bowled.
public int score()
{
  int points = 0;                                            // Cumulative count of points for the game
  int ball = 0;                                               // Current shot or "ball" (1 or 2 per frame)
  int frame;                                                  // Current frame of the game


  for (frame = 0; frame < max_frames; ++frame)
  {
    if (fallen[ball] == 10)
    {
        // Strike (all pins knocked over from 1 ball) gives bonus of next two balls
        points += 10 + fallen[ball + 1] + fallen[ball + 2];
        ++ball;                                                 // Move to next frame (no 2nd ball)
    }
    else if (fallen[ball] + fallen[ball + 1] == 10)
    {
        // Spare (all pins knocked over in 2 balls) gives bonus of following ball
        assert(fallen[ball + 1] > 0);
        points += 10 + fallen[ball + 2];
        ball += 2;                                             // Move to first ball of next frame
    }
    else
    {
        // Open frame just gives score of all fallen pins of both frame's balls
        assert(fallen[ball] + fallen[ball + 1] < 10);
        points += fallen[ball] + fallen[ball + 1];
        ball += 2;                                             // Move to first shot of next frame
    }
  }
  assert(frame == max_frames && ball == balls_bowled);
  assert(points <= max_frames*30);                // Maximum possible score
  return points;
}

Answer 3

Like kekoav, I am wary of naming something FooManager or FooController. Not only is it indicative of an object that suffers from an identity crisis, but it introduces ambiguity. I've worked on a project where there was an "AccountManager", which was a domain object representing a person who managed accounts (a subtype of Employee). Of course, someone made an "AccountManagerManager", and someone else got confused and created an Account domain object (which wasn't something our app was dealing with), then mixed stuff into AccountManager to manage the Account. It was kind of a mess.

Quis custodiet ipsos custodes? Quoque quis administro ipsos administratorum?

Yeah, my Latin is rusty.

Answer 4

I've been reading Clean Code by Robert C. Martin and hadn't made it to this section from chapter 17 yet but I think it gets the closest to answering the question.

N1: Choose Descriptive Names

Don’t be too quick to choose a name. Make sure the name is descriptive. Remember that meanings tend to drift as software evolves, so frequently reevaluate the appropriateness of the names you choose. This is not just a “feel-good” recommendation. Names in software are 90 percent of what make software readable. You need to take the time to choose them wisely and keep them relevant. Names are too important to treat carelessly. Consider the code below. What does it do? If I show you the code with well-chosen names, it will make perfect sense to you, but like this it’s just a hodge-podge of symbols and magic numbers.

public int x() {
    int q = 0;
    int z = 0;
    for (int kk = 0; kk < 10; kk++) {
        if (l[z] == 10)
        {
            q += 10 + (l[z + 1] + l[z + 2]);
            z += 1;
        }
        else if (l[z] + l[z + 1] == 10)
        {
            q += 10 + l[z + 2];
            z += 2;
        } else {
            q += l[z] + l[z + 1];
            z += 2;
        }
    }
    return q;
}

Here is the code the way it should be written. This snippet is actually less complete than the one above. Yet you can infer immediately what it is trying to do, and you could very likely write the missing functions based on that inferred meaning. The magic numbers are no longer magic, and the structure of the algorithm is compellingly descriptive.

public int score() {
    int score = 0;
    int frame = 0;
    for (int frameNumber = 0; frameNumber < 10; frameNumber++) {
        if (isStrike(frame)) {
            score += 10 + nextTwoBallsForStrike(frame);
            frame += 1;
        } else if (isSpare(frame)) {
            score += 10 + nextBallForSpare(frame);
            frame += 2;
        } else {
            score += twoBallsInFrame(frame);
            frame += 2;
        }
    }
    return score;
}

The power of carefully chosen names is that they overload the structure of the code with description. That overloading sets the readers’ expectations about what the other functions in the module do. You can infer the implementation of isStrike() by looking at the code above. When you read the isStrike method, it will be “pretty much what you expected.”

private boolean isStrike(int frame) {
    return rolls[frame] == 10;
}

N2: Choose Names at the Appropriate Level of Abstraction

Don’t pick names that communicate implementation; choose names the reflect the level of abstraction of the class or function you are working in. This is hard to do. Again, people are just too good at mixing levels of abstractions. Each time you make a pass over your code, you will likely find some variable that is named at too low a level. You should take the opportunity to change those names when you find them. Making code readable requires a dedication to continuous improvement. Consider the Modem interface below:

public interface Modem {
    boolean dial(String phoneNumber);
    boolean disconnect();
    boolean send(char c);
    char recv();
    String getConnectedPhoneNumber();
}

At first this looks fine. The functions all seem appropriate. Indeed, for many applications they are. But now consider an application in which some modems aren’t connected by dialing. Rather they are connected permanently by hard wiring them together (think of the cable modems that provide Internet access to most homes nowadays). Perhaps some are connected by sending a port number to a switch over a USB connection. Clearly the notion of phone numbers is at the wrong level of abstraction. A better naming strategy for this scenario might be:

public interface Modem {
    boolean connect(String connectionLocator);
    boolean disconnect();
    boolean send(char c);
    char recv();
    String getConnectedLocator();
}

Now the names don’t make any commitments about phone numbers. They can still be used for phone numbers, or they could be used for any other kind of connection strategy.

N3: Use Standard Nomenclature Where Possible

Names are easier to understand if they are based on existing convention or usage. For example, if you are using the DECORATOR pattern, you should use the word Decorator in the names of the decorating classes. For example, AutoHangupModemDecorator might be the name of a class that decorates a Modem with the ability to automatically hang up at the end of a session. Patterns are just one kind of standard. In Java, for example, functions that convert objects to string representations are often named toString. It is better to follow conventions like these than to invent your own. Teams will often invent their own standard system of names for a particular project. Eric Evans refers to this as a ubiquitous language for the project. Your code should use the terms from this language extensively. In short, the more you can use names that are overloaded with special meanings that are relevant to your project, the easier it will be for readers to know what your code is talking about.

N4: Unambiguous Names

Choose names that make the workings of a function or variable unambiguous. Consider this example from FitNesse:

private String doRename() throws Exception
{
    if(refactorReferences)
        renameReferences();
    renamePage();
    pathToRename.removeNameFromEnd();
    pathToRename.addNameToEnd(newName);
    return PathParser.render(pathToRename);
}

The name of this function does not say what the function does except in broad and vague terms. This is emphasized by the fact that there is a function named renamePage inside the function named doRename! What do the names tell you about the difference between the two functions? Nothing. A better name for that function is renamePageAndOptionallyAllReferences. This may seem long, and it is, but it’s only called from one place in the module, so it’s explanatory value outweighs the length.

N5: Use Long Names for Long Scopes

The length of a name should be related to the length of the scope. You can use very short variable names for tiny scopes, but for big scopes you should use longer names. Variable names like i and j are just fine if their scope is five lines long. Consider this snippet from the old standard “Bowling Game”:

private void rollMany(int n, int pins)
{
    for (int i=0; i<n; i++)
        g.roll(pins);
}

This is perfectly clear and would be obfuscated if the variable i were replaced with something annoying like rollCount. On the other hand, variables and functions with short names lose their meaning over long distances. So the longer the scope of the name, the longer and more precise the name should be.

N6: Avoid Encodings

Names should not be encoded with type or scope information. Prefixes such as m_ or f are useless in today’s environments. Also project and/or subsystem encodings such as vis_ (for visual imaging system) are distracting and redundant. Again, today’s environments provide all that information without having to mangle the names. Keep your names free of Hungarian pollution.

N7: Names Should Describe Side-Effects

Names should describe everything that a function, variable, or class is or does. Don’t hide side effects with a name. Don’t use a simple verb to describe a function that does more than just that simple action. For example, consider this code from TestNG:

public ObjectOutputStream getOos() throws IOException {
    if (m_oos == null) {
        m_oos = new ObjectOutputStream(m_socket.getOutputStream());
    }
    return m_oos;
}

This function does a bit more than get an “oos”; it creates the “oos” if it hasn’t been created already. Thus, a better name might be createOrReturnOos.

Answer 5

If you're in a .NET environment, you can use FxCop for guidelines. As far as naming a class, I usually will go with noun/purpose. You're exactly right, what does the Manager class do? If it's a controller class, call it ManagerController.

Answer 6

A good point is to use design patterns and you'll have all done :)