How to name things – Peter Hilton

Naming is hard, George Orwell already knew that in 1946 when he wrote an essay about it.

2015-04-24 14.03.22

The rules for good naming:

1) Never use a metaphor, a figure of speech or something you have seen before, like a SomethingFactory

2) Never use a long word where a short would do, eg compnay_person_collection vs staff

3) missed that, oops, will add it when the slides are provided.

4) Never use the passive when you can use the active

5) Never use a foreign or scientific phrase if there are English words for it

It looks like writing code is as hard as writing prose, so let’s look at a few writers who wrote down advice, there is a whole website dedicated to writing advice. Writers have been doing this for a long time, so let’s listen to them. They can write it done better anyway.

Bad names

Despite the advice of writers, naming is hard, so let’s start with doing it wrong first, always easier.

  • Naming things foo. If you look this up in github, you get 38 million results!

2015-04-24 14.27.07

  • Use long combinations of words: appointment_lisy, maybe diary is better.
  • Using vague words, like manager. You can be more specific, like bucket, supervisor,  builder, planner. Or get. Why not fetch, find, derive etc.

In summary:

2015-04-24 14.59.02

 

Why is the final one wrong? You could name it mountCamel, which is more funny 😉

Peter showed a lot of fun quotes and examples, but the nicest one, I think is one by Sam Gardiner: ‘If you do not know how to name something, you cannot know what it it

How could we do better?

We could become better writers, that will always help. Something that will help, says Peter, is to makes puns, because they often rely on double meaning, which is exactly what you want to avoid when naming things.

Code complete 2 has a whole chapter on the power of variable names, and Clean Code has a section too, but shorter.

Learn about your customers domain, read Wikipedia, or novels set in the domain. To practice, you can also start writing comments for your code. For every method, try to write a one sentence comment. If you can do it, okay, just delete it again, it is not needed. But if you cannot, is the code clear enough? Are the names?