Naming Convention

11 Aug 2024 » Opinion

Ever since I started working as an Adobe Analytics consultant, more than 10 years ago, I always recommended my clients to follow a naming convention. I probably should have done a better job of explaining the why and the how. They say it is better late than never, so I am going to redeem myself today.

The why

If you are or have been a developer, you are already used to following a naming convention in your file, namespace, class, and variable names. As cool as it is to create a variable called foobar, nobody is going to understand it. However, an index in a loop called i is a convention that everybody understands.

However, if you are not a developer and are thinking that, therefore, you do not need a naming convention, I am afraid to be the bearer of bad news: you still need a naming convention. Naming conventions can and should be applied to almost anything related to technology, no matter your role. Here you have a few reasons:

  • Consistency. We all feel very pleased when we see a set of anything that follows a structure. The best example I can think of is how Lacoste shops sort their polo shirts, always following a predefined order based on color. The same can be said of file names: if your folders have their files following a pattern, they look so neat.
  • Ease of search. When you know the pattern that the items in your catalog follow, you are going to find them faster. Many tools offer the option to sort by name, which is something we should take advantage of.
  • Common language. Many touchpoints are shared between business and technology teams and we all know how reducing the friction between them is a win-win situation. It is very annoying when each person follows their own standard. However, if all teams follow the same naming convention, there is no need to communicate what the item is about: everybody will understand it immediately.
  • Self-explanatory. Going one step beyond the previous step, if the name can include the contents of the item, it helps even more the team.

The where

If you are wondering where you should apply a naming convention, let me start with the TL;DR: everywhere.

For those of you who want a longer explanation, here it goes. I remember many years ago I saw a folder of an Adobe sales representative. He had everything perfectly named and you could easily know what each file was: AcmePresentation.pptx, AcmeProposal.pptx, AcmeSOW.pptx, AcmeCalculator.xlsx… I do the same with my personal photos: I put the date and the location in the folder names, so I know where to look for them.

Let me show you some examples applied to the Adobe technology:

  • Segment definition. Many Adobe tools support the creation of segments: Adobe Analytics, Adobe Target, AEP… Let’s compare Pedro segment 1 with CartAbandonment30Mins. I bet nobody can figure out what my first segment is about (and I will forget 6 months later), but all of you will easily guess the second. Do I need to explain any more?
  • AEP or AAM Data sources & destinations. The same logic as the segment definition applies.
  • AEP Schemas & datasets. Not only the names but the fields and field groups too.
  • Adobe Analytics eVars, props, events. This is my personal favorite, from my early days at Adobe.
  • Adobe Campaign or AJO configuration. This includes journey names, custom actions, and anything that is configurable.
  • AEM asset or folders. This is probably an area where a naming convention already exists; otherwise, it is impossible to manage. There are SEO implications too.

The how

I have never seen a tool that enforces a specific naming convention. You are usually allowed to do whatever you want, even the biggest monstrosities. So, it has to be us, humans, deciding beforehand how we want to approach the issue at hand. There is no such thing as a universal naming convention or a best naming convention. It all depends on the situation and the taste. What I can do is provide some guidelines:

  • Character set. I would start by recommending using only alphanumeric names from the ASCII printable table. I completely understand that this seems like an imposition from the English-speaking world. If you want to use your language, you may want to do a proof of concept to test what happens with characters like Ñ, Æ, or Ø, or languages like Arabic, Chinese, or Japanese.
  • Case. When you have to concatenate various words, you should not reinvent the wheel, use any of the standard cases:
    • camelCase: capitalize all words except the first one and remove the space between them.
    • PascalCase: capitalize all words and remove the spaces.
    • snake_case: combine all words simply by replacing the spaces with an underscore _, keeping all words in lowercase.
    • kebab-case: combine all words simply by replacing the spaces with a dash -, keeping all words in lowercase.
  • Spaces. I personally like spaces in names, as they make text more readable. However, this comes with two potential issues:
    • Names become longer and the UI usually limits how much it shows, thus showing something like My very long se... instead of My very long segment for cart abandonment.
    • Some technologies treat the space as a special character, and cannot be used in names. This is why the 4 cases from above were created. More modern technologies allow for spaces. YMMV.
  • Dates. I strongly recommend using the format YYYY-MM-DD or YYYYMMDD. For example, the day I published this post would look like 2024-08-11 or 20240811. I also recommend putting it at the start or end of the name. The reason for using this format is that it is automatically sorted by date.
  • Verbs and nouns. It is also a good idea to decide how to use these words. Should verbs be in infinitives or gerunds? Verbs before nouns or the other way round?

Finally, and it goes without saying, you must document this naming convention, provide examples, and share the rules with all stakeholders.

Enforcement

The real issue with naming conventions is that we are humans: we forget to read the instructions, we make mistakes, we do not care… And, as I have just said, tools do not usually offer a means to enforce a naming convention. So, how do we go about the offenders?

I can think of three approaches:

  • Do nothing. This seems to be the most common case. Most of us do not like confrontation and would rather let it go rather than tell someone that they have done something wrong and that they need to fix it. While I understand this approach, you will end up having all sorts of names. I would even argue why bother creating a naming convention if you are not going to enforce it.
  • Manual review. You could have someone to regularly the names. If a name does not follow the expected format, report it to the creator.
  • Automatic review. This is the one I like the most: have a process that regularly checks the names. It can be as simple as checking a regular expression or as complex as using sophisticated algorithms. You still have to decide what to do with any mismatch: delete the item, prepend a text to notify of the error, send an email…

 

Photo by Vlad Vasnetsov

Related Posts