2 Ways to Name Things Better in Programming
I don't mind spending a full 5 minutes coming up with a variable or database column name, because it's always worth it in the end.
Pretty much everyone has read the famous quote about naming things right?
There are only two hard things in Computer Science: cache invalidation and naming things.
The first one is very tricky, and it’s believably tricky because it’s a hard technical problem that requires pretty creative thinking to solve in a reasonable way.
But naming things should be easy right? How hard could it be. If you want to
save someone’s name in your database, just use name as the database column name.
Easy peasy.
# Run Your Names Through an Ambiguous Filter
In that example, now there’s an issue of “well, is it their full name or just their first name?”, and part of the issue of poorly picked names is a misunderstanding of what things do at a glance.
If you can’t tell what it should be a glance, now you need to break your flow and look it up in the documentation or crawl through source code to try and figure out what the intent was.
So, the first question to ask yourself after you’ve named something is, if I ran this through an “is this ambiguous?” filter, could it be considered confusing or have a double meaning?
If it helps you to remember doing this, think of this epic scene from Spaceballs where they comb the desert. If you do only this, you’re already ahead of the game.
# Use Natural Language to Guide Your Process
Here’s an interesting one, and it sparked me into writing this blog post.
A few months ago I was on a call with my buddy Scott, and we were talking about processing credit cards in a web application. We both knew using Stripe was a no brainer decision, but we got to talking about features.
Now… I’ve built a number of payment systems, and I even cover accepting recurring and micro-transactions with Stripe in great detail in my Build a SAAS App with Flask course.
He’s built a lot of payment systems too, but I recommended a nifty feature of displaying a banner to customers who have a credit card that is about to expire – which I cover in the Flask course btw.
A little info alert would let them know their card is going to expire soon. Something like “Your Visa card (4242) is going to expire next month”.
I ran down the gist of how it could work, and the approach I prefer is to store the customer’s last 4 digits of their credit card, along with the expiration date in a local database.
This way, it’s a simple date comparison to see if a card is going to expire in a few months. This is MUCH better than making a remote API call to Stripe, but that’s not the point of this post.
How Would You Describe a Credit Card Company?
He put together a database model on the spot and his first pass was to name
the credit card company field card_type. That’s not the worst name, and it
definitely describes what it is, but in the context of using it, it’s not very
natural.
For example, let’s say you had a CreditCard class. That means you would end
up calling CreditCard.card_type which to me is a little ugly. We already know
we’re dealing with a credit card, so there’s no need to repeat card in there.
Now, in Scott’s defense, he didn’t know I would be writing this blog post a few months later and at the time I wasn’t “testing him”, or anything like that. Scott is a good programmer and I’m sure that as soon as he started to use the code he wrote, he would have refactored the column name to something else.
My goal isn’t to call him out, it’s just providing a real life example of how these things work out and I’m super guilty of naming things poorly too.
I mentioned it might be a good idea to rename that to brand because writing
CreditCard.brand is very natural. I also had a slight bias because a day
before the call I was integrating Stripe on a different project and I know they
name it brand, and in cases like this, it’s a reasonable idea to align your
local names with what they are remotely (Stripe’s API in this case).
To my surprise Scott brought up a very good point. Personally, I thought brand
was brilliant. It’s short and describes it very well, but I also don’t own any
credit cards so my mental image of a credit card is pretty much empty.
On the other hand, Scott owns many credit cards and when he thinks of “brand”, he thinks of a bank’s branding on the card itself. That thought never crossed my mind.
Credit cards that are branded to a specific bank and theme:
That’s an interesting point. We didn’t discuss it any further at the time but after the call I thought about it for a while. I wonder if there’s a different name that could be used.
CreditCard.company could work, but it has the potential to be very
ambiguous in the case where a third party company might be associated to a
Credit Card.
CreditCard.merchant is another one but it fails right away because
the term “merchant” has a specific meaning in the payment world, and it’s
not how you describe a credit card company.
CreditCard.type may work from a natural language point of view but from
experience I know this will be trouble because type tends to be a reserved
keyword in a lot of programming languages and frameworks.
Next up there’s CreditCard.processor which I really like. This is very
descriptive and doesn’t have any second meanings. “Visa is a company that
processes credit card transactions”. I like it! If I were designing an API, that
is what I would choose and I’d be happy about it.
# There Is No One Right Answer
The takeaway here is that there is no single right answer, which
is why naming is so difficult in the first place. Technically all of the above
would work (except maybe for type). There’s no answer book that says
“yes, in the case of naming a credit card company, ‘brand’ is correct”.
The best we can do is spend some time to ensure what we name is very clear and hope it resonates with as many people as possible (especially yourself, for when you need to go back and maintain your code). Now you have 2 simple strategies that you can use!
Your challenge is to look through recent code you’ve written and try to name a few things slightly better. Let me know how it goes in the comments.