Meaningful Names — Breaking Down Clean Code Ideas

Welcome to this series of articles, breaking down the ideas from the book Clean Code.

This is the first of many articles in which I will go chapter by chapter and section by section, extracting the ideas of the authors of Clean Code in a few sentences or paragraphs.

You can use this guide to study before an interview, to refresh your memory with the Clean Code ideas, or as a helpful resource while studying the Clean Code book. You can use it however you want.

These articles do not include many examples, but they convey the ideas that the authors intend to convey from their examples in the Clean Code book.

Chapter 2 - Meaningful Names

Names in code are everywhere, so give them the importance they deserve.

To better name your variables, functions, classes, files, and so forth, the book suggests the following rules:

Use Intention-Revealing Names

• Names must reveal their intent. Choosing good names takes time but saves more than it takes.
• If a name requires a comment, then the name does not reveal its intent.
• You can evaluate a name by considering if it answers the following questions: why does it exist? What does it do? How is it used?

Avoid Disinformation

• Abbreviations are disinformative. It is best to avoid using them, as they can be confusing.
• Beware of using names that vary in small ways. For example, XYZControllerForEfficientHandlingOfStrings and XYZControllerForEfficientStorageOfStrings are very similar except for a single word. Avoid these minor differences as they can be confusing.
• Be careful when using the word List when naming variables. Only use it if the container truly represents a physical list; otherwise, it can lead to false conclusions.

Make Meaningful Distinctions

• Distinguish names in such a way that the reader knows what the differences offer.
• Avoid using meaningless distinctions just to satisfy the compiler regarding duplicate names.
• Avoid using words like Data and Info, as well as articles like a, an, or the. If they don’t make a significant difference, then don’t use them.
• Avoid using variables such as a1, a2, a3. Such enumerations are not always useful. Instead, strive to create meaningful distinctions.

Use Pronounceable Names

• If you can’t pronounce it, you can’t discuss it without sounding like an idiot.

Use Searchable Names

• The name of your variable has to be easy to search using your text editor or IDE.
• The length of a name should correspond to the scope of its usage.
• Use a constant variables instead of having a 22 or 44 floating numbers there.
• Longer names trump shorter names, and any searchable name trumps a constant in code.

Avoid Encodings

• Encoded names are seldom pronounceable and prone to mistyping. Avoid their usage.

Avoid Mental Mapping

• Readers shouldn’t have to mentally translate your names into other names they already know.
• There are exceptions, such as the variables i and j used for iterating arrays and matrices. This exception works because it’s generally known by programmers.

Class Names

• Classes and objects should have noun or noun phrase names, not verbs.

Method Names

• Methods should have verb or verb phrase names.

Don’t Be Cute

• Do not use too clever names.
• Do not use culture jokes.
• Choose clarity over entertainment value.
• Say what you mean. Mean what you say.

Pick One Word Per Concept

• Be consistent with the concepts of the words. For example, Controller, Manager, and Driver have similar meanings. Choose one and maintain consistency across the project.

Don’t Pun

• Avoid using the same word for two purposes.
• Words like add, insert, and append can mean the same thing. The idea here is to identify the concept or intention that those words have for your project. Think in this way: Does this new add method I want to implement follow accordingly with the other add methods? Does it follow the same concept?

Use Solution Domain Names

• Remember that the people who read your code will be programmers. Therefore, feel free to use computer science (CS) terms, algorithm names, pattern names, mathematical terms, and so forth.

Use Problem Domain Names

• Use problem domain names from customer requirements only when the problem is too precise and cannot be explained meaningfully using other words.

Add Meaningful Context

• Ask yourself if the variables, functions, and everything around them are in accordance with the context.
• Ask yourself: where do these variables/functions make the most sense? Where are they best understood? You can move the variables/functions to a class or file; the idea is to move it to where it best fits.
• Every time you try to make a change, move a function, or create a class, ask yourself if the context still makes sense. Sometimes, while adding new features, the context does not make sense anymore; we should think about this again.

Don’t Add Gratuitous Context

• For an imaginary application called ‘Gas Station Deluxe’, it is a bad idea to prefix every class with GSD. Not only is it redundant, but if you want to export a class named GSDAccountAddress outside the GSD app to another project, this class will be out of context.