Lessons from natural languages for naming variables and methods

Naming is a difficult thing to nail down as a developer. Most variables have to be clear both in technical as functional context. However as with most language the vocabulary may shift over time as the product/app develops. Old usages my be replaced, but forgotten to be refactored.

There are a few things I took from learning natural languages that gave me more tools to get to better names.

Context is important

Names should be clear in context. There is hardly ever a need to make naming perfectly clear without any context. Awesome if it is but often that takes far more thought than I think it is worth.

So take the word ‘tie’, it could be a noun or a verb. Yet it will probably be crystal clear when used in a sentence. This sentence is created by the surrounding names of objects, classes, variables.

The class a field is defined in will give it context. The method name and class a parameter is defined in will give it context.

Simple example:

class Car {
    Door driverSide;
}

class Door {
    void open() { ... }
}

...

myCar.driverSide.open()

Interpretation

In natural languages some words may mean vastly different things in different regions. The same can be true when writing software. While it is probably not a good idea to mix meanings inside the same codebase. It should be acceptable to have the same variable mean different things for different teams.

This however also places the burden on new developers joining a domain to adopt to the usages already established. So before bringing up new terms always check in with yourself to see if what you’re going to propose is actually clearer or just what you’re used to.

Clarity over brevity

While run-on setences are generally discouraged a longer sentence can provide just that bit of clarity to make sure other people reading it know exactly what you mean.

Similar for variables names. Short names can make it harder to create enough context and can cause conflicts when you need 2 instances of the same class. Instead of going for ‘car1’ and ‘car2’ going for ‘myCar’ and ‘myNeighboursCar’ might give more meaning to the code.

Create sentences

Continueing with the sentences theme. We can actually create sentences closer to natural languages making the code easier to read and understand. This is especially powerful when used in BDD or DDD as you’ll focus on defining the right verbs and nounds that make sense your domain.

Example:

void drawAnyShape(Shape someShape) {...}

struct CircleShape {...}

var shape = new CircleShape()

drawAnyShape(shape)

vs:

void draw(Shape shape) {...}

struct Circle {...}

var randomCircle = new Circle()

draw(randomCircle)

Renaming is possible

Lastly I want to emphasise that unless the naming is in some interface used by others, renaming is easy. So when naming some internal variable or method don’t spend days on thinking the right name. It might come next time you look at the code, rename it then.