Naming conventions

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

Naming is one of the most difficult things that we do, one of the most important, and one of the most common. We name lots of things in our day-to-day work:

• Git repositories and directories.
• Modules, classes, functions, and variables.
• Cloud resources like AWS buckets, EC2 instances, or security groups.
• System configuration options like user roles, dashboards, or Kubernetes clusters.
• And the list goes on...

The naming conventions on this page are intended to align our naming practices with eye toward inclusion and usability, and hopefully make the job of naming things a little bit easier.

Start with the user

Names are a reference to a thing or a concept. They provide a shorthand that we can use to reference something, so starting with who is going to use the name and how they are going to use it will best ensure its effectiveness.

To do this, we can ask questions about a user other than ourselves, or imagine ourselves coming back to the name in the future. For instance:

• Will a new engineer be able to find the S3 bucket they're looking for without asking for help?
• If we're coming back to a function that we wrote two years ago, will we understand what it does from the function and parameter names alone, or will we need to read through the body of the function in order to understand it?

Accurate, clear, brief (in that order)

Borrowed directly from Norton's usable writing guidelines, this guideline applies to naming for the same reason it applies to UX writing.

1. Names should be accurate first.
   • Inaccurate names will confuse and mislead readers. Left unchecked, inaccurate names can lead to bugs (we expected a function to do one thing but it did another) or a breakdown of communication due to different mental models of the work.
2. Names should be clear second.
   • When there are multiple accurate ways to describe a resource, we should prioritize the name that is the least ambiguous.
   • This is especially important when we're working in overlapping contexts that use the same word to mean different things. For instance, using the word "component" with a frontend team will refer to UI elements, but an infrastructure team uses "component" to mean a discrete piece of the architecture. If those two teams need to work together, they may want to agree on a different word to remove that ambiguity rather than overloading the word.
3. Names should be brief last.
   • If we have multiple accurate and clear candidates for a name, we should choose the shorter, simpler name.
   • Avoid shortening words whenever possible (see spell out the whole word).

Spell out the whole word

Shortened or abbreviated words require the reader to translate the word in their head, an extraneous cognitive task, or mental energy that is not essential to our work. And there's no guarantee that we will be able to accurately perform that task—we might not understand an abbreviation's meaning entirely or we might mistake it for another meaning.

Cognitive effort is our most valuable resource, and one we want to spend on interesting engineering tasks, not trying to figure out what a word means. Avoid the impulse to shorten words for the convenience of the author, because it takes fewer keystrokes, or to fit it into an artificial space limit (hard character limits are rare).

1. Don't shorten a short or common word. Common examples:
   • Use "wwnorton," not "wwn".
   • Use "work(er)," not "wrk".
   • Use "read-only," "readOnly," or "read," not "ro".
2. Use full names in source code and minify for production.
   • Minification is the process of translating code to its smallest form, and will turn many long names into short ones. This gives us the best of both worlds: clear names in the source code and the smallest possible names in production, where we want small file sizes.
   • Trying to use short names in our source code for performance reasons is a classic example of premature optimization.

It may be okay to abbreviate or shorten a word in some circumstances:

• When the abbreviation is commonly verbalized (said aloud), or when it is commonly used outside of Norton.
  • For instance, when talking to each other, we say "NCIA" instead of "Norton Cloud-based Interactive Assessment," and we may say "auth" more often than "authentication".
  • Conversely, we say "Smartwork," not "SW" or "SW5".
  • "K8s" is a commonly-used shorthand for Kubernetes and may be okay to use in contexts where everyone is familiar with Kubernetes, but should be avoided when there's a chance someone might not understand it.
  • Tip: having to regularly explain an abbreviation is a great signal that we may want to stop using it.
• When there are very strict character limits. This is incredibly rare for our technology stacks and platforms.
  • The most common place this is true is Jira issue keys, which must be short.
  • This is NOT the case for most named artifacts on GitLab, AWS, or in our code.

Use business domain words

Our business changes more slowly than engineering practices, so favor names that describe the business concern like "course-analytics" over more generic, engineering-focused names like "data-lookup". When the business uses radically different words than engineering, we should establish a ubiquitous language with our colleagues to decide on words that are used by everyone. This a core part of domain-driven design, a practice that is an especially useful mental model for naming.

Avoid translating in code

Our code should directly reflect our domain model—our shared concept of the business logic and objects—including the actual names used in implementation, such as functions and variables. When we find names that are different in the code than they are in meetings, tickets, or other business artifacts, we should work with our team to reconcile those differences, either updating the code or changing the words we use in our business artifacts.

Don't include implementation details in the name

Implementation details—or the specifics of a solution—can easily leak into places they shouldn't, facilitated most often by the words (names) we use. This can be difficult to identify, but removing these details from our named resources and concepts can help align efforts and create more lasting, resilient work.

We often discover that a name is based on an implementation detail when that detail is no longer applicable. In these instances, it's best to change the name rather than trying to force the work to fit the name.

Example: deployment repository names

We once used the naming convention "*-docker" (for instance, "ebook-docker") for our application deployment repositories because they housed the Dockerfiles, as well as environment definitions (Kubernetes files) that we use for deployments. But when we decided to move Dockerfiles to their application repositories to facilitate continuous delivery, it no longer made sense to include "docker" in our deployment repository names.

Including "docker" in the name forced us to rename the projects later because it was a specific technology that wasn't essential to the purpose of the projects—it reduced the resilience of the projects.

Example: naming a project

We once named a project the "Single source of truth" project because the goal was to remove duplicate data across our systems. But during the course of the work, we discovered that some parts of the data actually needed to live in different systems, which meant the name was no longer accurate. We managed to shift focus and rename the work, but not without effort and time.

In this case, a specific solution—the idea of a single source of truth—shaped the work in ways that were difficult to correct because it was part of the name.

Document the details

Teams that follow more strict and specific naming conventions should document them in project readmes or in official product documents on SharePoint.

For instance, document casing conventions such as when to use camelCase, snake_case, kebab-case, or PascalCase.