Naming Things in Code

The classic quote is “There are only two hard things in computer science:

cache invalidation and naming things”.

I do agree that these are hard to get right, but

they're also easy to get wrong.

And we can get 80% of the way by avoiding

bad patterns.

We're going to talk about

what I consider to be bad naming practices, practices

that if you avoid you’ll force yourself into better naming, the classic

first example you'll see is you shouldn't name variables with a single letter.

I suspect this originally came from when math

and computer science were more or less the same.

Mathematicians pride themselves on being terse.

They like to crystallize down to the smallest, most concise way of expression.

The thing is, you don't need to edit math, but you do need to edit code.

So it's become obvious to programmers that we should avoid using single letter

variable names because they don't tell you anything about the variable.

But I'd argue that you should take this one step further.

You should never abbreviate names, period.

Look at this code.

Can you tell me its purpose?

What about now?

Abbreviations rely on context that you may or may not have.

You spend more time reading code than writing code.

So forcing yourself to understand per system naming patterns

makes it much harder to dig into unfamiliar code.

Abbreviations used to help because of two reasons:

It saved you typing

and screens were 80 characters wide.

But now, when we write code, we get this.

It takes less keyboard strokes than ever to write variable names.

And we have massive 4K screens now.

So there's no real advantage to abbreviation.

Don't put types in your name.

If you've edited older code on Windows,

you'll see something called Hungarian notation.

This is where you'd prefix the type to the variable name.

I think this goes back to before we had good standard types in C,

so everything would basically be int

and the type of the variable wouldn't actually tell you what was inside of it.

But now with statically typed languages,

the type should tell you exactly what you're looking at.

So putting types in your variables is no longer necessary.

Related,

it's considered good practice to put units in your variable names.

For example, if you have a function that accepts a delay time.

If this value is in seconds, you should name the variable delaySeconds.

This way it's clear to the user of the function

that they better be putting in seconds.

It's also more clear to someone

editing the class itself what unit they're working with.

But even better than that is to have a type that removes the ambiguity

completely.

For example, in C#, the time span

or chrono::duration in C++.

The type abstracts the user from understanding the exact underlying unit.

You need to explicitly ask for a unit back.

Like here, getting seconds back.

For dynamically typed languages like Python,

you sadly can't rely on type declarations to help.

So we'll need a bit of help from the variable name.

Interestingly,

people also add types to their types.

In C# there's this pattern of prefixing interfaces with “I”.

This is something I have never understood.

Good code uses interfaces all the time and the consumer doesn't

really care whether it's an interface, class, or abstract class.

They just want to know what they can call.

In this code, we animate an object on the screen.

This is an interface.

If I swap this to an abstract class

or a concrete class, it wouldn't change this code.

Nor would it help the code do anything better.

C# is still following this pattern, even for new .NET library code.

So for your C# code, it might make sense just to follow the pattern.

Since bad style guidelines are better than no style guidelines.

For other languages, I’d definitely avoid.

Another example of typing your types

is if you find yourself naming a class with “Base” or “Abstract”.

This I've never found in a standard library.

If I have a “Truck” class and then realize that

it might make sense to create a parent class instead.

I've seen folks name the new parent class “BaseTruck”.

This isn't a great name because it doesn't help the users of the class.

It still represents a truck.

If you ever find yourself unable to come up with a good name for the parent

class, it probably means that we should actually rename the child class instead.

Instead of “BaseTruck”, let's just name it “Truck”.

And for the child class lets over specify the name.

We'll call it a “TrailerTruck”.

Now, if someone gets a truck, they understand what they're getting.

It's a truck.

And they don't need to know about any of the details of subclasses.

And if they need to know

a specific type of truck, well, then they get the specific name.

Sometimes if you're struggling to name

something, it's actually indicative that the code structure is to blame.

A common anti pattern I see is if there's a collection of functions

used widely in the code base,

but it's all bundled up into a single utils class or module.

If you're thinking of naming code “utils” or “helper”,

you should think if it's really the right spot for it.

Here's some code from a no doubt that processes movies.

There's a bunch of util functions here.

Firstly, we should consider whether some of these methods

actually make sense as a part of their respective types instead.

So this code here, we can actually just move into the movie

class itself.

For some of these, we can instead create a class that represents

a collection of movies and that has the desired methods.

And finally, some of these

can be separated into other classes with descriptive names.

The paging functionality can be moved into its own class,

and we can even make this generic if we want,

so that it can operate on more than just movies.

And the cookie function should really just be in a cookie class.

Now we don't have anything in our utils class, so we can just delete it.

You don't see a bundle of utils in standard libraries

because they can all be sorted into modules that have good names.

So we should do the same in our code.

These few rules will help you write code

that is easier to read and change.

What would you add?