Naming Things Is Hard

When making software, you have to name a lot of things. There are functions, classes, numbers, data models, etc., and they all need meaningful names to ensure better communication within a team.

Over the past few months, I’ve noticed a few things that make naming things hard in a software project. These difficulties may be stressful, but they also highlight the benefits of good naming conventions.

Accurate Discussion with Your Team

If you’re working with another developer, it’s helpful to have a common vocabulary when solving a problem. Misaligned terminology can lead to inefficient conversation, which in turn can lead to faulty assumptions and an incorrect implementation of a story. That’s why it’s so worthwhile to spend time clarifying and unifying what certain pieces of data should be called.

One common example of a name I use that isn’t accurate enough is “id.” I might know that a variable called “id” is referring to an ID of a product model. However, if I’m pairing with another developer who might not have the same context as I do, my pair might assume it refers to an identifier for a different data model, like a store ID.

This particular example is easy to fix. Just change “id” to “productId.” But the same issue can happen when naming a more abstract idea or concept. It can be tough to name classes or functions in a way that prevents faulty assumptions.

Clear Communication with Stakeholders

By naming things in the codebase in a way that aligns with the stakeholders’ understanding of the system, you can improve communication with those stakeholders. Using a common terminology will make it more natural to talk to people who will use the system but aren’t involved on a technical level on a day-to-day basis. It’s easy for a dev team to agree on what to name things, but the team’s understanding of the system might not match up with the mindset of the software’s end users.

Whenever I get stuck on what to call a particular piece of data, I try to see things from my client’s perspective. How would they refer to a particular metric or data model in the system?

If that answer isn’t obvious, it might be a sign that some clarification is needed to keep your views aligned. It’s a good idea to spend time with your stakeholders, clarifying the terminology so you can all talk about and understand the problem.

Consistency for Future Team Members

In most software projects, the first team to work on the project won’t be the last. Other developers will eventually join the team, and they’ll need to ramp into the project. By using consistent names across the codebase, you can help new developers identify patterns in the code.

Often, terminology evolves over the course of a project. For example, one section of the application may refer to a metric as “units per case.” However, another section developed a few months later may refer to that same metric as “case size.” While that might not trip up the current team, this small change may be a stumbling point for other developers. To avoid confusion, strive to maintain consistent names throughout the whole project.

I hope this has been helpful, and I’d love to hear about other naming practices you use to maintain good communication.

  • Todd Chapman says:

    I have also been thinking about this a lot lately. In the large product I work on we sometimes make the mistake of naming functions based on their implementation details instead of their purpose, which makes it difficult for someone who is reading the code in preparation for an unrelated change. Understanding why an operation is being performed is as important as understanding the implementation. In fact, I think that naming functions based on the implementation can make it easier to overlook alternative solutions.

  • Comments are closed.