Naming Conventions: Why You Need Them for Clean Data

When it comes to data collection, the best way to set your company up for success is to establish consistent naming conventions from day one. This will not only make it easier to read your code, but it will also mean that everyone at your company can easily understand what your events mean.

In this article, we'll go over why you need a strong naming convention for analytics and how to implement our recommended approach, the object-action framework.

What are naming conventions? 

Naming conventions in data analytics are rules devised by data analysts to clearly identify and categorize the completion of “events” with your product or service. Naming conventions are critical to ensuring the consistency and accessibility of your data.

Benefits of naming conventions

If you really want to make the most out of your data, you have to be thoughtful about how you name analytics events and where they live in your codebase. If you don't, your data management will get messy because different developers will implement tracking at different times with different preferences, resulting in a hodgepodge of events that are hard to read and analyze.

You might not realize, but there are actually a bunch of different ways to name the same user interaction. Take, for example, the simple action of a user signing up for a newsletter. You could implement the event as "Sign up," "Signup," or "User Signed Up."

Without a consistent naming convention, your teammates will be left guessing which event actually corresponds to a user signing up for your newsletter. This may not seem like a big deal, but imagine how confusing this will become as your company grows over time.

To avoid getting into this situation and enable your company to actually use data, there are two simple things you can do today:

• Align on a framework for naming your events and properties (down to the casting).
• Put a process in place to enforce your company's framework

Getting these two things right will bring consistency, convenience, and clarity to your data and the decisions you make with it.

• Consistency: The biggest benefit of using a clear framework is data consistency. If all different data types and events are named the same way in each tool, it's easier for you to use those tools. One framework. No questions.
• Convenience: You're likely going to continue to add new tracking as your company ships new features and products. Having a standard naming convention means that each time a developer implements a new call, they won't have to think about how to do it
• Clarity: With engineering, product, analytics, and growth teams relying on the same data, enforcing standards means everyone can easily understand what each event means. This enables your teammates to run ad hoc analyses and launch experiments using data that is organized and easy to understand.

The object-action framework

If you only take away one thing from this lesson, remember that the most important thing to do is to pick a single naming framework and stick with it.

At Segment, we implement analytics using the object-action framework. Our success team developed this convention after working with thousands of customers on their analytics setup.

The idea is simple. First, choose your objects (e.g., Product, Application, etc.). Then define actions your customers can perform on those objects (e.g., Viewed, Installed, etc.). When you put it all together, your event reads Product Viewed  or  Application Installed.

We like the object-action framework because it makes it easy to do the following:

• Analyze the performance of a particular feature: "I want to build a funnel to see how many people who view products also add them to their cart. Sweet!" The events related to products are all next to each other in alphabetical order.
• Quickly scan a list of events to find what you're looking for: "Where are all of the product events? Nope, Nope. Got it."
• Impose a standard any marketer, analyst, or developer can understand: "I'm guessing this event called Product Viewed  is about folks viewing products."

Now that you've got the basics, here's a deep dive into how to use the object-action framework with some examples.

Choose your object

The first piece of the object-action framework is the object. These objects are the key "pieces" of your app and website that your customers are interacting with. It's probably easiest to understand what a business object looks like with a few examples.

List how users can interact with them

The next thing to figure out is how users can interact with those objects in your product. For example, a user can view a product or book a hotel.

Choose the properties to collect with each object

We recommend tracking general events like Product Viewed  along with properties that give you more details. With just the top-level event, you can analyze how often and how many people view your products. But you wouldn't be able to see which products and categories were the most popular.

When thinking about what properties to collect, you usually want to collect the same properties for the same object, no matter which action they are associated with.

For example, across events like Product Clicked , Product Viewed , and Product Shared , you'd want to collect a common set of properties related to products, for example: category , product_id , price , brand.

With these properties, you can easily figure out the most viewed and shared products and categories.

Be specific about casing

When you're documenting each of these events and the properties associated with them, you also want to be crystal clear about the casing. This might seem nitpicky, but it's imperative in the long run.

Here are the five most common options:

• all lowercase — account created
• snake_case — account_created
• Proper Case — Account created
• camelCase — account created
• Sentence case — Account created

We like Proper Case for events and snake_case for properties.

Put it all together

Putting this all together, it's really easy to construct your events.

Object Action:

• object_properties

Song Played:

• name
• artist_name
• album
• label
• genre

Document these events in your tracking plan and make sure to implement them in code with the same formatting.

In code, it would look something like this:

analytics.track({'Song Played',

  name: 'What Do You Mean',

  artist_name: 'Justin Bieber',

  album: 'Purpose',

  label: 'Def Jam - School Boy',

  genre: 'Dance Pop',

 });

Other options

Of course the object-action framework isn't the only way to do this. You can use any order of actions and objects, and any type of casing. You can also do present or past tense.

The only thing that really matters is that you keep it consistent!

One other practice to avoid is dynamically creating new events with unique variables. You will never be able to make any sense of your funnels. Plus, your bills for your analytics tools will get out of control.

For example, sometimes we see people pass through the unique email with every sign up in the event name. You're much better off keeping those as properties.

Don't send sign up events as analytics.track('Sign Up - jake@segment.com');

Instead, send them as analytics.track('Sign Up', {email: 'jake@segment.com'});

Hopefully this deep dive into the object-action framework gave you some inspiration for keeping your data squeaky clean. We can't stress how much you will thank yourself down the road when all of your events adhere to the same naming convention.

Have a different way you like to name events? Let us know on Twitter!