Software Design and the Art of Naming

Throughout my career as a software developer and architect, one of the questions I get asked most is, “What should I name this?” In software development, as well as in many other fields, naming things is par for the course – from naming databases, database tables, stored procedures, classes and files to naming variables, REST endpoints and git repositories. The list could go on, and each example is worthy of a separate discussion. However, I want to talk about the importance of naming objects thoughtfully, regardless of the domain.

For most developers, naming things doesn’t rank high on their priority list. Let’s face it – as developers, we usually have plenty to do, and what we’re currently working on should have been done yesterday. As we develop applications, our mindset is often on the bigger picture: the application’s core functionality. Deciding on names for our projects, classes or variables ends up getting in the way of completing the application, and we have bigger fish to fry.

What you choose to name something matters

Humans, not just computers, need to be able to read software elements like code and databases. Naming things deliberately and with thought, I would argue, is as important as any other task when building an application. Having proper names for objects gives applications, and any related systems, a self-documenting nature. A well-defined and consistent naming scheme serves as a guide for any subsequent add-ons or modifications to applications, making it clear what a variable’s purpose is or how to use a specific class. The more clear and descriptive the name, the more you can avoid reverse engineering by conveying transparent meaning and intent.

What is the process?

In my view, the naming process involves two parts.

First, you have to define a naming scheme, which you can either create or adopt (if one already exists). Regardless of which path you choose, a naming scheme should dictate the pattern and rules of naming something in a particular domain, such as a C# variable or a database table. The following are some attributes to consider for your scheme.Word-combining/casing

  • camelCase
  • PascalCase
  • snake_case
  • kebab-case
  • all-lower

Scope designators

  • Example: prefixing an underscore “_myVariable” to denote a global variable

Using noun/verb combinations

  • Example: getCustomers, Customer_Get, Customer_Add

The second part is to employ the scheme. It’s important to remember that while a scheme dictates the convention to follow, it doesn’t tell you what to name an item specifically. This is where you want to use good judgment and consider the domain and context in which the item exists. A name that’s too long and verbose can detract from the readability. However, if a name is too short, it may not convey enough information to someone unfamiliar with the code. The object’s purpose should be evident.

Don’t be afraid to compose your object names using full words unless the abbreviated form is more well known, such as “sendHTTPRequest()” versus “sendHyperTextTransferProtocol().” The acronym “HTTP” in this case is well known, so there’s no need to spell it out. A name should be as long as is necessary to clearly convey what it is and its purpose – and not any longer. You want someone who is unfamiliar with your code to be able look at the object and have a basic understanding of its intended use .

Don’t standards already exist?

Like most things, it depends. The intent of this post isn’t to focus on particular domains. Some, such as C#, have well-established schemes for naming variables and classes. Other more specific domains, such as the schema names or stored procedure names within a SQL database, may not. Ideally, you want to search for established standards and best practices within the specific domain and try to leverage what the community has done already.

One thing I’ve noticed is that there are often significant disagreements in the public domain on what the standard is or should be when it comes to naming conventions. When you encounter this, I feel it’s best to do your research and ultimately choose a scheme that fits your scenario. It’s important to have a system selected and labeled as standard. Companies often already have a scheme in place, which makes this part easier.

Be careful using internal monikers

In the past, I’ve seen class names, database tables and other objects named after external companies or internal product and feature names. I suggest avoiding this, as you can easily end up building a large codebase or database schema over time with these names peppered throughout the system. Customers you integrate with will come and go, and internal product or feature names will change over time. But using internal monikers will leave you stuck with the original naming scheme because it was used so pervasively and is now too impractical to change. Try using names more generically tied to what the application does, rather than using a flashy marketing name.

Tools can help to enforce the standard

There are several tools (e.g. JetBrains ReSharper and StyleCop for C#, JSHint for javascript and TSLint for TypeScript) that can help define naming rules to enforce certain aspects of your scheme. Using humans as the only enforcement mechanism for your naming scheme will inevitably leak violations into your codebase over time. These automated tools can help reduce leakage and promote consistency. However, it’s ultimately up to the developer to select an appropriate name. To my knowledge, there’s no tool that can name your objects meaningfully and automatically.

Names Matter

In software development, names matter. There’s no one rule or standard for naming objects in most cases, and you’ll almost always find people who disagree with a particular style or system. I believe a fundamental rule is to be consistent and use a clearly defined system. It may not be perfect, but far worse would be a system that employs many different schemes within the same context or, arguably worst – no system at all.

Written by Jason Negrete,
Principal, Software Architect