Use Intention-Revealing Names

Make the code easier to understand by using clear, descriptive names for variables, functions and constants.

When names describe their purpose or role in the code, it become easier for other (or even for yourself) to understand what the code does without having to guess or remember hidden details. This helps make the code more maintainable and easier to change later.

Avoid Disinformation

• Avoid using names that mean something else like hp to mean hypotenuse its confusing why? because hp is also a name for some unix system, better to use ”hypotenuse” or ”hyp”,
• Avoid using the wrong type name, don’t call something ”accountList” if it is not a list because list has a special meaning for programmers, better to use ”accountGroup” or ”bunchOfAccount” or just ”accounts” would be better.
• Beware of using names that are too similar for example ”XYZControllerForEfficientHandlingOfStrings” and ”XYZControllerForEfficientStorageOfStrings”, these names look the same. It’s hard to see the difference, better to make names more different, so they easier to understand.
• Avoid Using letters look like numbers, like l small ”L” looks like 1, o (big ”O”) looks like 0.

Make Meaningful Distinctions

Don’t just change variable names to make the compiler happy. Make your names meaningful, if you have to make names different, make sure the difference actually matters and say something.

• Number-series names: Names like a1, a2, a3 etc, are not wrong to the compiler but they are useless to humans. They don’t tell us anything about what’s going on.

• Noise words: Words like Info, Data, Object, Variables etc, these don’t add any real meaning.
• Similar names: The variable moneyAmount is indistinguishable from money, customerInfo is indistinguishable from customer, and accountData is indistinguishable from account. Distinguish names in such a way that the reader knows what the differences offer.

Use Pronounceable Names

Humans are good at words. A significant part of our brains is dedicated to the concept of words. and words are by definition pronounceable. It would be a shame not take advantage of that huge portion of our brains that has evolved to deal with spoken language, So make your names pronounceable.

Some developers write names like this:

These names are hard to say and hard to understand. You can’t talk to your team and say ”Check genymdhms or pszqint” that sounds weird.

By the way "genymdhms" stands for generation date, year, month, day, hour, minute and second, but it’s hard to figure out what it mean.

Use names that are easy to say instead of "genymdhms" use "generationTimestamp", now you can say ”Hey look at the generationTimestamp it’s wrong”.
“Easy to talk about. Easy to understand”

Use Searchable Names

Single-letter and numeric constants have a particular problem in that they are not easy to locate across a body of text.

• Numeric constants: For example if you have a constant like MAX_CLASSES_PER_STUDENT, it is easy to search for it in your code, but if you just write the number 7 in many places, it is hard to find where you used that number.
• Single-letter: The same problem with single-letter names like “s” or “e”, the letter “e” is very common in english and in code, so it is hard to find the right “e” you want.
• Preference: the length of the name should match its scope, small scope => short names, large scope => longer, descriptive names.

Avoid Encoding

Encoding means adding extra information in the code, like the type or scope, for example writing strName to say this is a string or iCount to say it is an integer, it makes names hard to read because you need to learn the rules of the encoding.

New people who join a project must learn this extra code, which is confusing.

Interfaces and Implementation

When using interfaces and classes, some people write names like :

• Interface: IShapeFactory 
• Class: ShapeFactory

Putting ”I” before the interfaces it’s old style and not helpful, So if we need to encode either the interface or implementation we choose the implementation

• Interface: ShapeFactory
• Class: ShapeFactoryImpl

Avoid Mental Mapping

Don’t make readers guess or translate your variable names in their head.

The names should be clear and easy to understand. Sometimes people using single letters like i, j or k for loop counters, this is ok because it’s very common and easy to understand in small loops. But in other cases using one letter like c is bad, because the reader have to remember or guess what c stands for.

Smart programmers sometimes like to use short or tricky names to show they are clever.

But professional understands that Clarity is king, they write code that others can understand easily.

Class Names

A class represents something, like a thing or a concept. So class names should be nouns or noun phrases like Customer, WikiPage, Account, AddressParser, etc.

Avoid generic or unclear words like Manager, Processor, Data or Info these don’t clearly tell what the class really does or represents.

Method Names

A method performs an action, so it should be a verb or verb phrase like postPayment(), deletePage() or saveProduct().

If it’s a getter, setter, use JavaBean-style getName(), setName(”Mike”), If you're using ES6 get and set keywords, skip the prefix.

If it’s a Booleans should start with: is, has, can, should, was, hasPermission(), canEdit(), isLoading().

Don’t Be Cute

These are slang or jokes from a cartoon or a movie, you might think it’s funny, but other developers may not understand it and you may forget what it means after some time, it’s not clear what the function really does.

These names say what the function does simple and clear.

Pick One Word per Concept

If you pick one word to mean something, use it everywhere, don’t change it.

user.fetch(), product.retrieves(), order.get(), all of them do the same thing (get data), but you used three different words, and that’s confusing, let’s pick one word like get() and use it everywhere: user.get(), product.get(), order.get(), now it’s clear and easy.

Another example, let’s say you name your classes like this: DeviceManager, ProtocolController, USBDriver, what’s the difference between a ”Manager”, ”Controller” and a ”Driver”, maybe they do the same thing! But the names are different, so we get confused. You should pick one word maybe ”manager” and use it for all DeviceManager, ProtocolManager and USBManager now your code is consistent.

Don’t Pun

Avoid using the same word for different concept, let’s imagine that we use the name ”add”:

• order.add(item): which puts an item in the list
• calculator.add(a, b): which does a + b

Same word different meaning. That’s a pun, it look the same, but it’s not really the same action.

Use different names for different ideas

• order.insert(item)
• calculator.add(a, b)

now it’s clear. No pun. No confusion.

Use Solution Domain

When you’re naming your code use the power of technical terms that other developers can understand.

JobQueue this is clear to any developer, it’s a queue of jobs/tasks.

Using names like this save time because other developers don’t need to guess or ask what it does.

Use Problem Domain Names

When you write code that reflect real world-business logic, use names from the business domain, for example if you’re building a system for car garage use names like:

• Invoice
• Mechanic
• CustomerVehicle

Add Meaningful Context

Sometimes variable or function names don’t mean much on their own. You need to give them context by enclosing them in well-named classes, functions or namespaces when all else fails then prefixing the name may be necessary as a last resort. instead of just a state, write addrState this tells us it’s a related to an address not a game or app state.

These variables are used to build a message like ”These are 5 guesses”, but the names have no meaning on their own.

Now it’s obvious these are part of a guess statistics message.

Don’t Add Gratuitous Context

When naming classes, modules or functions, avoid adding unnecessary prefixes that repeat the application’s name or domain.

Imagine you app is called ”Gas Station Deluxe”, it is bad idea to prefix every class with GSD. Example:

It's not helpful because when you type 'G' and use autocomplete, you get a long list of classes. Use shorter names when possible, but always make them clear and provide meaningful context.

Final Word

1. Picking good names is hard it need good thinking and a shared cultural background.
2. Many people don’t learn naming well because it’s not a technical or business skill it’s a teaching issue.
3. Use refactoring tools to rename.
4. Clear naming helps in the short term and the long term.