Naming things

When we develop software, we name things. Things like variables, functions, methods, classes, interfaces, exceptions. Also database, database tables, columns in those tables. We name files our software uses or creates: configuration files, log files, lock files, temporary files… The list goes on.

And yet, how much thought do we put in in naming these “things”? Why should we care?

Why is naming important?

When we develop software, we make approximations of problems from the real world. We take those problems and we model them in software. These models help us solve the problems, but they are never perfect. They can’t be, because we lose information in the process of “translating” the real world problem into code. That’s why it’s important for us to preserve, as much as we can, the names of the concepts we are translating into code.

Good naming is important for the future programmer who will read the code. That future programmer can be anybody, with experiences ranging from none to over 20 years. It can as well be us, the authors of the original code.

Context matters

A big problem with naming things is that, when we are naming, we have all the context around that name built up. At that moment, we know why we are choosing that specific name. We’re also writing other code around that name, which gives us additional information and, well, justification, for why we think it is a good name.

But if we give that code to another programmer, or even if we ourselves revisit it after some time, most of the context that we had when we were writing that code is gone. The name might not be as good anymore like when we were coming up with it.

For that reason we have to consider what information will be available when reading the code, how the lack of the context we take for granted when writing, will affect the meaning of the name we chose.

When we’re coming up with names for things in our code base, it’s helpful to “switch” our mindset from writing code to reading code. Take a look at the names with this “reader” mindset and consider is the name giving answers to the whys, whats, and hows, or is it just creating an even longer list of questions?

Where will we use it?

It is also important to consider where in our code base will we use the thing we are naming?

Imagine we’re writing a repository to find a list of products from the database. We create an interface like this for it:

/** [@return](http://twitter.com/return) Product[] */ 
ProductRepository::find($filter): array

Looks okay, makes sense at the moment of writing this code. Later on we, our someone else, writes some other code that uses our repository of products:

$products = $this->repository->find($filter);

Still when we write this code, we know what it does. But lets switch our mindset to “reading” code. There’s at least three different questions that stand out: what repository are we working with, what are we finding, and by what criteria? The $products variable can give us a hint, a suggestion, but we need to double check to be sure.

A better line would be:

$activeProductsInTimePeriod = $this->productRepository->find($filterActiveProductsInTimePeriod);

Now we don’t have to guess and look at other code that we’re finding active products in a given time period. Someone will argue that the names are too long, or that the InTimePeriod appears twice in one line. Yes, but it appears twice only in this one line, we don’t know where else will be the $filterActiveProductsInTimePeriod or the $activeProductsInTimePeriod variables be used. In every other line they appear, these “long” names will carry enough context and information to the reader of the code that they will have no, or very little, questions about our code.

Make the names searchable

When naming things, we also have to consider that at some point we will want to search for that name across the code base. How unique is the name, how easy it is to find it among other similarly named things? Going back to our product repository example:

$products = $this->repository->find($filter);

All four names are hard to search for: products, repository, find, filter. They are not unique in any way.

If we look at the example with the improved namings:

$activeProductsInTimePeriod = $this->productRepository->find($filterActiveProductsInTimePeriod);

Here only the find method sticks out as not unique enough, so we should maybe look for a name that is a easier to search for.

There’s much more to naming things, and to naming them well. For the end I want to leave you with a good presentation on naming things by Peter Hilton: https://www.youtube.com/watch?v=SctS56YQ6fg

What’s your biggest challenge in naming things?