Notifications
Article
Naming Things is Hard
Published 14 days ago
33
0

What's in a name?

‘There are only two hard things in Computer Science: cache invalidation and naming things.’ - Phil Karlton
I certainly am not the first and won't be the last person to trot out that famous quote. It is worth keeping in mind when you sit there staring at your code trying to figure out what to call a particular script, you are not alone, not by a long shot.
The thing is though, too many people get hung up on the fact that they are naming something in CODE and forget that naming things in any situation in life is hard. If you ever find yourself getting stressed about what to call something, just remember companies make millions each year with books titled things like:
Where is the book titled "6001 names for a script that moves the camera, but also makes sure it doesn't clip into walls"?

Software names are not special

Naming things does make up a surprisingly large part of the process of writing software but that does not mean there is anything special about the way software developers do it compared to Movie writers or Toy makers.
It is difficult for developers precisely because it has nothing to do with software development. Uncle Bob said it best:
The hardest thing about choosing good names is that it requires good descriptive skills and a shared cultural background. This is a teaching issue rather than a technical, business or management issue. - Robert Martin
As Bob rightly puts it, naming is not really a programming problem, it is a problem of understanding how that name will be used, by who and in what context. It may sound funny, but programmers rarely think about why they are naming something. Do you? Have you ever really considered what the point of a name in code is for? Who it is for?
A computer doesn't care what something is called.
The class name could be AdT_aEfdDTR for all it cares, though I imagine remember it and typing it out a lot would get difficult. Not only that, imagine trying to TALK about it! Imagine being in a team and trying to describe a bug:
"Huh, we keep falling through the floor I think there is an issue in the "AYD ah EEE FDUHTR"
I guess we can add pronounceable to the list of requirements for a good name. Check.

A Canoe by any other name

We have established communicating with others is a major concern, another obvious one is to distinguish one thing from another. A Duck and a Horse are different things. Even if you never heard of them, you won't assume they are the same thing. The thing is though, you HAVE heard of them. you DO know what they are (I assume). This speaks to another part of this discussion. A shared vocabulary. In other words a glossary:
an alphabetical list of words relating to a specific subject, text, or dialect, with explanations; a brief dictionary.
We not only share a common understand of words as people but in specific fields there are words that have meaning we just "know". If you are a shoe maker, you might very well use the term Aglet in conversation with another shoe maker. You wouldn't feel the need to explain it, similarly if you created a charity and was talking to another person who runs a charity you could casually throw around the word 501c and not have to explain yourself.
It is worth noting that a name not only tells you what a thing is, but also gives you clues as to what it does. If you were looking through a list of my scripts and saw:
You might have an inkling of an idea about what it does. Why? Spawner is just a word, just like aglet or 501c, why does that word give you more information than the others?
The names you choose are not just chosen for another person, they are chosen specifically to be read by people working ON YOUR PROJECT. This is not worth ignoring. your names are talking to people with Domain Knowledge. Specifically if you are writing code in unity, your code is talking to developers, most likely software developers, most likely game developers. The kinds of people where a term like spawner has specific connotations. Using words that relate directly to the domain you are in will more clearly define what your code does. With that in mind, let's have a look at some of the most common words in software development.
In short, depending on the context of your project, maybe you can replace an EnemyCharacterCreator with a MobSpawner.

System Manager Controller Services

If we want to pick names we have established it needs to be pronounceable and should use words that the person reading it would know. Nothing can go wrong now right? Any java developers? You might be familiar with the spring framework, a shining example of Enterprise Software development.
So maybe name length is a concern...
Software can sometimes get complicated, in fact I would go so far as to say software ENJOYS getting complicated. The more specific and detailed a system gets, the more likely you are to end up with a complex hierarchy of managers, controllers and systems. A giant soup of classes that all sound really complicated and Code-y. Let's have a look at an example. Say I have a game where you play as dragon. What do you call that class?
  • DragonManager ?
  • DragonSystem ?
  • DragonService ?
Must be doing a lot of complex stuff. It is a system after all. The thing is though, to revisit the question before:
Who are we naming things for?
You know your audience. Your audience is you, so with that in mind: what do the words "System" "Manager" and "Service" mean to you? If I am honest with myself the answer is..... NOTHING! They are just words that mean:
"Does stuff with the word before this".
If I made a "DragonSpawner" and a "DragonInput" Do those things feel like they do something different from each other? would you know what they are? Do those suffixes give you more information about why they are called that? For me they do. would changing that last one to "DragonInputManager" tell you any more information? Prefix and Suffix words are not bad. They have their uses, it is just important to avoid NOISE WORDS. words which feel like they are adding value to the thing you are naming, when in fact they do nothing but make the name longer.
There is also another interesting thing to note about the above names. Do you think a DragonSpawner handles input? does the DragonInput handle spawning? They might. Though if they did it wouldn't feel right. What about the DragonManager? He probably could do both, and much more! Maybe that is why the word Manager is so enticing. It doesn't specify exactly what it does, so that frees it up to do anything and everything. It may not tell you what the details of the class functionality is, but it does tell you one thing. There is a very good chance you have yourself a God Class .
In summary, a name not only tells you what something does, it tells you what it should ONLY do. It tells you it's Single Responsibility.

Nouns and Verbs

Clean code is simple and direct. Clean code reads like well-written prose - Grady Boosh
Up to this point we have been talking about naming classes/scripts. We are naming the entities, the "things" in our code. If you are developing software these days there is a very good chance you are writing code in an Object Oriented way.
You treat your actors as nouns and the actions they perform as a collection of verbs. This has an interesting effect of making your complex code read and sound like a robot trying to speak English.
Rather than being a confusing jumble of brackets and letters your code can be written in such a way as a non-programmer could understand it.
fox.quick = true; fox.color = Color.brown; dog.lazy = true; fox.JumpOver(dog);
sometimes it can be tempting to write elaborate and complex names that explain what something does, without thinking about the context of how it will be used. Let's take a simple example
public class XboxController { public bool ControllerConnectionActive = false; public void CheckIfControllerConnected(){} public void UpdateControllerInput(){} }
Those names seem nice and clear. I can tell exactly what they are doing. Let's use them:
XboxController xboxController = new XboxController(); xboxController.CheckIfControllerConnected(); if(xboxController.ControllerConnectionActive) { xboxController.UpdateControllerInput(); }
So, I can tell this code certainly does something with an xbox controller, and there is some connections involved. It is a little hard to tell specifically what it is doing though. There is a second part to that Grady Boosh quote:
Clean code is simple and direct. Clean code reads like well-written prose. Clean code never obscures the designer’s intent - Grady Boosh
Let's try a small rewrite of that last bit of code:
XboxController controller = new XboxController(); controller.CheckConnection(); if(controller.IsConnected) controller.Update();
It is a subtle change, but knowing that I will be calling the controller object, there is no need for me to specify the controller in the names of my function. I can be economical. Not only that, when checking the connection, I will be using it as a question, a condition. knowing this, I can phrase it such that it's use appears to ask a question. IsConnected vs Connected. In this case both are valid, though in a slightly different context of say a Door class. It would avoid a lot of confusion to write if(door.IsOpen) and door.Open() rather than try to discern if the verb is meant as a question or as a statement of intent.
Keep this in mind if you ever find yourself writing UpdateInput on an input manager or calling highscoremanager.GetPlayerScores() maybe a highscores.Get() would do.

Conclusion

This is only the start of the topic of names, there is still the question of using shared naming conventions, whether to use PascalCase or camelCase. The question of hungarian notation and the value of style guides. There is a lot to think about when it comes to names, though if you keep in mind:
  • who is going to read this name?
  • what does this name tell someone about what this code does?
  • is it easy to have a conversation about this code?
  • do you have to be a programmer to understand roughly what it does?
It is hard to go too far wrong.

Tags:
Jason Storey
Software Developer and Contractor - Programmer
7
Comments