The importance of being specific
There are only two hard things in Computer Science: cache invalidation and naming things.
— Phil Karlton
Yes, this quote is over-used in development. While it lends itself well to plenty of jokes, it also underlines the importance of naming “things”, which by itself is an ironic example of the underlying problem: “things” is not a good name.
Fortunately, some rules, guidelines and best practices have been established, and yours truly believes they can be easily learned, applied and followed during development. Naming “things” well is a component of writing good code, and should not be discredited just because it’s not a functional part of it. Let’s go over some examples.
Conventions and consistency
Whatever you do, be consistent and adhere to conventions. These can be of different types.
Sometimes standards can have functional impacts too. Vue in its style guide recommends naming components with two or more words. This has a practical reasoning behind, components will be inserted alongside HTML tags as <ExampleComponent />. Naming a component “article” might break it, since HTML already has an <article> tag. What to do if nothing better comes to mind? Well, maybe call it “TheArticle”, or even better “AnArticle”, in opposition to “singleton” components such as “TheNavbar”.
Following rules in naming a specific type can make your code more readable. If you have to put payments in an array, it should probably be plural: “payments”. If you were to name it “payment” you might very quickly have to make some awkward decisions, such as what to name its elements in an iterator such as payment.map(singlePayment => […]). Similar best practices exist for other types:
– Arrays: use plural names
– Booleans: hint the type by having them start with with is, has, can
– Numbers: add specificity to it with: base, maximum, total, minimum, etc.
– Class methods and properties might have an inferred semantic context, which is the name of the class itself. That means that inside a class Potato, you might not want to have a method getPotato. You might just want to call it “get”. That method will be called on the class in any case, so Potato.getPotato() might be a bit redundant, while Potato.get() is easier to read and straight to the point.
Developing a jargon or glossary
A big help in establishing naming can come from the jargon of the field of your clients. Working with financial institutions your clients most probably have a very established and battle-hardened jargon that solves your problems, and at the same time ease communication with them. You don’t even need to fully understand what the term means for the clients, you as a developer bring a different set of skills than your investment manager client. I still don’t truly understand what a “ledger” is, but I do know what it means in our codebase, to my team and with our client.
To consistently use a set jargon might not be easy, especially early in a project. Writing it down under the form of a glossary might strengthen its usage and avoid ambiguity. Having a glossary for every project might not seem necessary at the beginning, but it is a form of documentation that will help you, your team and clients down the line. Different projects might have different glossaries. “Order” in an e-commerce application means one thing but something very different on a religious platform. Depending on the day and time “bar” might make me think of beers or charts. It’s important to separate glossaries per project or domain.
My college professor in simultaneous interpretation would get quite upset if we used generic words when we knew the right one. “A man walking on the street” takes quite a bit of time to say and while it might mean the same as “pedestrian” it often doesn’t. The act of walking is what’s important. The man remains a pedestrian if he’s walking on a square. Gender is most probably not important, so “person” would be a better choice than man, and “pedestrian” takes care of that too.
The same thing applies to development. “User” is omnipresent because of its genericness. “Customer” might be better for e-commerce. On a lending platform, your users might further be split into “borrowers”, “lenders”, “loanees” and “applicants”. This provides accuracy. You are effectively scoping your code to better understand which “users” exactly you are referring to.
Another very recurring example in development is amounts, sometimes referred to as values or numbers.
If you realise that the “amount” will have to be split into a before and after tax amount, don’t just create “amount” and “amountWithTax”. Change “amount” to be “amountWithoutTax”. Now that you have more information at your disposal you can imbue new meaning to the original “amount” variable. If you want to push it further, you might want to see how all these amounts are called in the financial field, which might lead to “amountGross” and “amountNet”. Or it might lead to confusion, because you’re not really writing a FinTech app, and your team members and/or future you are unfamiliar with the differences between gross and net, but know what taxes are.
But be careful. It’s not like writing code for an hour straight, then running it and fixing that you did wrong. Wrong variable names don’t throw exceptions. Pack all the meaning you can into a single variable name without being wrong.
Benefits of good naming
A good, consistent naming strategy will help you stay on track with your project. It will act as a reminder of what it is that you are actually doing in terms of business logic. It will make you think a bit longer before diving into writing code, why it is that you’re writing it and what you’re trying to accomplish. It can facilitate communication, as your team will be consistently referring to the same things by the same name. It can make searching through your codebase easier, as well as refactoring it. It can save you time checking what type a variable is and make your code more seamless and readable. It can help you understand and focus on your client’s needs better. It can help onboard new developers by using widely accepted standards they know and understand.
And all of this comes at a low cost of thinking what the name of the “thing” should be before writing it. And that’s the difficult part, just look at the title of this article.