Naming Things Is Hard

Names are everywhere. They are our mind's way of abstracting the complexity of the universe. In the world of software, we are always engaged in crafting new abstractions to describe our everyday realities. A common quip in the programming world is naming things is hard. Coming up with a name isn't always hard, but coming up with a good name usually is.

In the previous chapters, we have explored the principles and theory underlying abstractions. In this chapter, we'll provide the final key to the puzzle. An abstraction cannot be a good abstraction without good naming. In the names we use, we are distilling a concept, and that distillation will define how people end up understanding the concept. So, naming things isn't just the provision of arbitrary labels; it is the provision of understanding. Only via a good name can a user or other programmer...

What's in a name?

Breaking down the key elements of a good name is difficult. It seems to be more of an art than a science. The boundary between quite a good name and a very good name is fuzzy and liable to subjective opinions.

Consider a function that is responsible for applying multiple CSS styles to a button. Imagine a scenario in which this is a standalone function. Which of the following names would you consider to be the most suitable?

• styleButton
• setStyleOfButton
• setButtonCSS
• stylizeButton
• setButtonStyles
• applyButtonCSS

You've likely picked your favorite. And there is, among those of you reading this book, bound to be disagreements. Many of these disagreements will be founded in our own biases. And many of our biases will have been conditioned by factors such as what language we speak, what programming languages we've been previously exposed to, and what...

Naming anti-patterns

Much like the abstraction-building warnings of DRY and YAGNI, naming has its own warnings and anti-patterns. There are many ways to compose a bad name, and nearly all of them can be split into three broad naming anti-patterns: needlessly short names, needlessly exotic names, and needlessly long names.

Names are the initial lenses via which we and others will view the abstractions we build. Therefore, it is vital to know how to avoid creating lenses that only end up obscuring understanding and complicating things for other programmers. Let's begin by exploring needlessly short names and how they can end up drastically limiting our ability to understand what something does.

Needlessly short names

Names...

Consistency and hierarchy

So far, we've talked about the three most important characteristics of a name: purpose, concept, and contract. One of the easiest ways to bestow these characteristics upon your names is to use consistency and hierarchy to your benefit. Consistency here refers to using the same pattern of naming across many different names within a given area of code. Hierarchy, on the other hand, refers to the way we structure and put together different areas of code to form a holistic architecture. Together, they allow us to give a name a rich context that can be used to make strong inferences about its purpose, concept, and contract.

This is best explained by looking at the JavaScript directory of a fictional app. We have a directory full of files, like so:

app/
|-- deepClone.js
|-- deepEquality.js
|-- getParamsFromURL.js
|-- getURL.js
|-- openModal.js
|-- openModalWithTemplate...

Techniques and considerations

JavaScript, due to its ever-changing nature, has gathered a huge variety of conflicting conventions. Many of these conventions garner strong opinions either in support or in disapproval. We have, however, settled on some basic conventions around naming that are more or less globally accepted:

• Constants should be named with underscore-separated capitals; for example, DEFAULT_COMPONENT_COLOR
• Constructors or classes should be camel-cased with an initial uppercase letter; for example, MyComponent
• Everything else should be camel-cased with an initial lower case letter; for example, myComponentInstance

Apart from these foundational conventions, the decision of naming is left largely up to the creativity and skill of the programmer. The names you end up employing will be largely defined by what problems you're solving. Most code will inherit naming...

Summary

In this chapter, we have wrestled with the difficult art of naming things. We've discussed the characteristics of a good name, that is, purpose, concept, and contract. We've walked through examples of how to weave these characteristics into our names and what anti-patterns to steer clear of. We've also discussed the importance of hierarchy and consistency in our pursuit of clean abstractions. Finally, we have covered several helpful techniques and conventions that we can utilize when we're having a difficult time naming things.

In the next chapter, we will, at last, begin to delve into the innards of the JavaScript language itself and learn how to wield its constructs and syntax in a way that yields truly clean code.