The importance of being descriptive when naming

There are only two hard things in Computer Science: cache invalidation and naming things.
Phil Karlton

TL;DR: Don't overthink and just be as descriptive as you can when naming code.

Naming things is hard. For example. When my wife was pregnant with our daughter we agonised for months over her name before coming up with her name and we still aren't sure if we picked right. What if she doesn't like her name when she grows up?

Naming code can almost seem just as hard. We think 'there has to be a perfect name to give this code justice'. We think that it has to be clever, memorable. concise and snappy.

Some common pitfalls

• We can try to be too clever and end up with some obscure name

const exoticOptimiser = () => {}

• Or we can try to use some clever reference.

const iWantToBeTheVeryBest = () => {}

• We also see a lot of shorthand. Some are acceptable like event-handlers eg.

(e) => {} // e for 'event'

• Some are just pure laziness

const myLazyFunction = (a, b) => {}

But all jokes aside poor naming has terrible consequences. I've seen some horrid naming in my short career, as I'm sure all of us have. Debugging and working with poorly named code is an avoidable nightmare.

The importance of good naming

It's very likely that at some point in the future you won't be around to explain why you named a function in a certain way.

Even if you are still there, you may forget why a function or some code was programmed in a certain way.

If the name was formulated poorly there is a large likelihood you may lead the developer down rabbit holes.

For example, what would you think if you saw this function?

const calcAB = (a,b) => {}

Calculate what? Is it even calculate? What is this function doing with a and b?

Sure you can read the code, but what if the code is 200 lines long? You've already wasted an opportunity to clearly identify the purpose and functionality of the function.

Imagine instead you saw this:

const calculateTheDistanceBetweenPoints = (pointA, pointB) => 

Sure, it's much longer but it's readable and clear and descriptive. Even naming the parameters as pointA is so much more clear than just saying a and b.

What I think is the right way

Naming code isn't like naming a baby. You don't know how the baby will turn out once they grow up! But you know exactly what the code is supposed to do (or at least I hope you do!). You have all the ingredients to write a good name.

My 2c is that it's best to be as descriptive as you can. Describe the code.

• If it is a variable call it exactly what it is.
• If it is a variable describe what it's supposed to do.

Forget being concise. Focus on being precise.

You may end up with names that are quite long. But this is so much better than a name that is concise but obscure.

If it is too obscure and you can't think of a good name, maybe it is actually indicating code smell and your function is not very good. If so great! You should refactor :)

Steps that I follow

Some steps that I follow to make sure that naming leaves a legacy and not a nightmare are:

1. Be descriptive about what the code does.

2. Review the name and make sure that it can't be interpreted in multiple ways.

3. For especially complicated functions, I specifically ask for feedback about the name in code reviews.

Conclusion

Write names that are descriptive, even if it is long! Remember that code is supposed to be readable - if it isn't it is bad code and naming is huge factor in determining if code is readable.