Why Bother With Naming Conventions?

Naming conventions are worth bothering with because on a small data team the biggest cost is not tools, it's people's time. A naming convention is an agreed pattern for what things are called, and naming alignment means that pattern holds across the whole stack: database, schemas, dbt project, Git branches and security roles. When the names line up, anyone can tell what an object is and where it lives at a glance. When they don't, every developer pays a small tax of figuring it out, every time, and that tax compounds across the project. The same inconsistency also trips up AI coding tools, which run with whatever they find. It feels like a small thing, and the impact on daily efficiency is very real.

Where naming misalignment shows up

If you lead a small data team, or you're one of the only engineers at the company, you already know that time and money are under a microscope. Naming is one of the less obvious places to get efficiency back.

The audit

When I work with a team one on one, one of the first things we do is an audit. We go step by step through what they have today: the database, the dbt setup, the Git repo, security roles, all of it.

Naming is one of the first things that pops out, especially on smaller teams, because it's rarely consistent. The questions we ask:

• Database. What are the warehouses and schemas called?
• dbt project. What is the project named, how are folders and directories named, and do they match what gets deployed to the database?
• Git. Do branch names follow a convention through the workflow, or does everyone skip over it?
• Security. Do the names of roles and users match what those groups actually do?

Each of these might make sense in isolation. To be a well oiled machine you want them working together, looked at from a higher architectural level as one system.

An example of four components that don't line up

Picture four pieces of the same stack, each named by whoever built it:

• A database called analytics_prod, which was the name of the first database I ever worked on
• A dbt project called dbt_yourcompany
• A repo called data-warehouse
• A role called prod_rw_role

Individually each one is fine. Together, you can't tell at a quick glance whether they represent the same thing. Even the small stuff is inconsistent: underscores here, dashes there. It has no cohesive feel.

Why it happens and the common excuses

I don't believe this happens on purpose. Teams were moving fast, it got overlooked, and it's much easier to talk about in theory than to actually do. When I ask why a name is the way it is, the answers are usually one of three.

• "We'll fix it later." It won't happen. Foundational names like a database or a folder directory get set once and never touched again, until things are so messy you need a full migration.
• "It's not a big deal." It is, for the reasons below.
• "We didn't think about it." This is an awareness gap, and the most fixable of the three. Hopefully this serves as the reminder.

It's not that teams lack good intentions. It's that the decision gets made quickly and then becomes permanent, so it's worth understanding the cost at the moment you make it.

Reason 1: It's easy to explain

The naming convention alone does a lot of the heavy lifting. If your staging models are prefixed stg_, that matches the staging directory in your dbt project, and that matches the custom schema in the database, then anyone who sees the model knows where it lives and what it represents.

Nobody has to explain it every time. The same goes for your warehouse layer and your marts: each layer named a certain way, each one aligned across the project and the database.

Roles work the same way

A role called analyst or loader tells you who it's for. A vague name, or a string of acronym letters nobody remembers, means someone has to go ask whether it's the right role to use.

Easier to navigate, easier to onboard

When the database, Git project, dbt project and roles tie together, you understand where things live and can move between them without bothering anyone.

Onboarding gets easier for the same reason. Less tribal knowledge means a brand new person can understand what's in place, repeat the process, and be effective right away instead of relying on you to explain everything.

Reason 2: Maintenance is the highest cost

This is probably the biggest reason. It's easy to fixate on the cost of licenses and tools, and those matter, but most of the time the real cost is the people on the team. Salaries and contracted rates make every hour spent decoding conventions very real money.

Slower to figure things out

Without a consistent naming process you figure it out every single time. It takes more mental bandwidth and more clock time.

There's an old saying from the dbt community: newlines are cheap, brain power is expensive. Being a bit more verbose and clear costs nothing. Decoding terse, inconsistent names costs you every day.

Harder to repeat work

Every new model means deciding what to call it and what the process is, like starting from scratch. With a clear convention you rinse and repeat. No extra thought, just forward progress.

Constant task switching

Every time you stop to double check what something means, or compare it against something else, you mentally start over. Those seconds pull you out of the flow state where real work gets done.

Friction across the whole project

One of my first jobs in data engineering was writing and managing very long stored procedures. Every time I opened a new one it was like entering a different world. Different naming, different query structure, all of it hard to read and hard to change.

The first thing I'd do was reformat the whole query: spacing, capitalization, indentation. Once it was clean I could see what was happening and move through it quickly. The difference in speed was dramatic, and it was purely about consistency.

Every moment spent re-sorting and re-navigating is a moment not spent on something productive, and all of it has a cost.

Reason 3: It's easier to use AI

Onboarding a human is hard when the project is inconsistent. The same is true for AI coding agents and tools, with one difference: a human might pause and ask questions, while the AI will just run with it and do something on your behalf.

Bulk changes break

An AI tool wants instructions to follow. Give it an inconsistent project and it returns inconsistent results. Many teams want to throw a pile of work at a coding tool and have it solve everything, but without a consistent base you don't get what you asked for.

You end up spending more time reviewing than the AI saved you. I think that will change over time, but today, the fix is to establish the strategy up front before going further.

Hard to leverage AI tools at all

If everything is ad hoc, AI has nothing to lock on to. It will make its own interpretation, still move quickly, and leave you double checking whether it was right.

At that point you may not even know what to say. You agree with whatever it tells you, and that's a recipe for more chaos. Being responsible with AI means having a strategy it can follow.

Real talk

Nobody likes being nitpicked. Specific critiques about names can feel tedious, even a little passive aggressive, and it's tempting to say you'll get back to it.

But this is one of those things that pays dividends over the long haul, or quietly costs you in the other direction. If you're getting started, or you have the chance to readdress it, look at your naming and make sure it's all in alignment.

Related reading

• Are Strict Data Conventions Helpful or Overkill?
• The Power of Naming in Data Projects (especially w/ dbt)
• dbt Project Naming Conventions: Recommendations
• Don't Overlook Workflow (as a Small Data Team)

Final takeaway

Naming alignment is one of the first things I check when I audit a small team's stack, because it predicts how much time they lose every day. Names are the labels on everything else you build. Get them aligned early and the project gets easier to explain, maintain and hand to a tool or a teammate.