How to Name Things 💬

Finally addressing the hardest problem in software.

There are only two hard things in Computer Science: cache invalidation and naming things.

Phil Karlton reportedly came up with this line during his time at Netscape, in the late 90s, and it has stayed one of the most popular programming jokes ever since.

A common trait of successful jokes and comedy is that they reveal some surprising truth, in a witty way. In fact, I even believe that laughing is something we developed, as human beings, to show appreciation towards others’ brilliance — but I digress.

So if that programming joke got so popular, it’s because it’s true in some way.

Leaving aside cache invalidation for today, during my career, naming things well has been indeed very hard, and very often.

I believe such hardship comes from two factors:

• ⬆️ High importance — good names are important for a surprisingly long list of deep reasons, from software to communication.

• ⬇️ Low consensus — there is surprisingly little out there about how to name things in software. If you search for resources and articles (as I did), most advice focuses on low level rules about basic hygiene, like using snake_case or camelCase, or starting boolean vars with is or has. Well, that’s not what makes naming hard.

So, as always on Refactoring, let’s address this from first principles, and move top-down from them.

This article is a collection of ideas, mental models, and tactics that have served me well over more than 10 years. It is bound to be controversial and you may not agree with what I say, but even if you disagree with most of it, if it makes you think more about this subject while doing so, I consider it a win!

So here is what we will cover today:

• 💬 Names matter — why good names go a long way, and why bad ones are worse than you think.

• 📡 Systems and services — naming strategies for your big architecture pieces, and the feud between clever and descriptive names.

• 📂 Folder structures / architectures — discussing discoverability, using context, and a critique of the screaming architecture.

• 🔧 Naming classes and functions — discussing nouns, verbs, prefixes, and grep-ability.

• 📊 Keeping consistency — good rules are only half of the job.

Let’s dive in!