The Hidden Skill and Art of Naming Things

The two hardest problems in programming are cache invalidation, naming things and off-by-one. You learn a lot about algorithms while studying computer science to find clever solutions for the problem at hand - but for naming things?

For me undoubtedly this is the hardest problem. In fact, this issue exists in almost every discipline, whether you are pioneering a field and are the first one to name your discovered thing(s) or on a daily basis when communicating with your co-workers. As developers, we face this when communicating with our PM on our specs or with designers on sketches, mockups, or components.

While studying sports science it is common (and required) to start with a definition first and then use it along the way. In computer science, this of course happens for the technical terms but isn't considered for actually writing software to solve a problem in a certain domain. During my software engineer apprenticeship, I remember in some situations getting tips and discuss naming things on the spot for domain-related terminology. In university, for the handful of computer science courses I had, nothing - this was left out. I can't remember a linguistic course for this, that I think would come closest for teaching this.

Discussing naming things at work is often seen as unnecessary and considered a waste of time preventing you from getting the job done. There might be some truth to it, as it wouldn't necessarily matter for the current task you might be working on, but the pain becomes "visible" when the next person has to deal with your (improper) naming. When the naming doesn't click immediately or doesn't do what the name suggests, it gets hairy and the problem is passed on to the following person (that might even be your future you). Sometimes, it's wise to take a shortcut when the context is not known well enough to give it a proper name (note to developers: please put a comment in your code).

What Makes a Good Naming?

A good naming is already encoded in the term ubiquitous language and it's enough to describe it in two points:

• A non-technical/industry language eliminating inaccuracies understandable by a multi-disciplined team
• No ambiguity!

You could say there are some people who spent more time on naming things than others. I've realized there is some mastery level to naming things, roughly:

Level 0 - Just name it with the first thing that comes to mind
Level 1 - Your naming suggest what it does properly
Level 2 - With your naming a consumer can no longer use your thing the wrong way
Level 3 - Your name is a beauty and makes the consumer smile, it leads to a positive emotional benefit. This is where you begin to imagineer and reach for art (this is the bonus level - hardly reached).

Important Note: This is not really a mastery level, like you shall NOT say: "I'm at naming things level 2". It's only a short, quick, and non-exhaustive scale for use within this article!

Ambiguity is clearly the enemy of good and clear naming and it almost ever happens unintentionally. I consider this problem solved, when reaching level 2 with your naming, the gap from level 1 to 2 is the hardest to jump.

Naming things as a skill will unfortunately often go unnoticed, rarely praised and honored. Instead, it will most often be recognized when it's done (completely) wrong.

Test Yourself with an Example

Let's use this wireframe (below) as an example. Imagine you are about to develop this screen which contains three sets of information. The application in which this is going to be used, is an international app and the contents for the text are stored in locale files, your job is to give these variables proper names. Easy huh?

There is a straight forward way to name these three variables:

1. Headline
2. Tagline
3. Text

Boom! you would think, you found three variable names that get the job done quickly and can move on. But later your brain starts to think: is it really a headline? What about heading or header? What even is the difference between the three? As web-developers, we can at least relate header to an equivalent <header> element that is there to structure the document into semantic sections. That's the first relief here, disconnecting header from headline and heading. Identifying header as a structural thing allows for more connections to related concepts.

Where else is structuring used to section documents? For me, I have explored this in LaTeX and HTML, each of these technologies comes with mechanics to provide structure.

• HTML: Mainly <article>, <section>, <header> and <footer> as well as <h1> to <h6>
• LaTeX: Most of \\part, \\chapter, \\title, \\heading, \\subheading etc.

The name of these mechanics can also help us create a guided structure for naming our variables in an entire project. These names are good candidates to prefix and structure our locales. An important learning from that little exaggeration is that the name of the variables are sourced from the technical implementation (if applicable). This is good knowledge to assist your naming and maybe come up with some guidance on semantics. It's not yet enough to land on the final design for the naming but a little success and very good input.

Left is the unclarity between headline and heading. I am not a native English speaker and I don't know the nuances between them linguistically, which is a problem we see occur quite often (as English is the language of international teams as well as development often happens in English, too). A possible explanation, I came up for myself, is that it depends on the context/discipline we are in. From a marketing perspective, this would perhaps tend to be more of a headline, which is important to attract the interest of a possible reader. On the other side, in scientific writing, a heading is quite fine to summarize the following section or it might be a required field for the article format/magazine you are publishing for.

Discussion

Even with what seems to be a simple example there is a lot to learn and explore around, which gives more context to land on a proper naming. The example shown is one I haven't solved for myself yet, but it's good practice to explain the levels I described earlier:

Level 0 - Take the first naming
Level 1 - With a bit more investigation, come to a solution that feels has more of a proper naming
Level 2 - The naming resolves in a convention of what words to use for what purpose. At this point, you can't get the naming of your variables wrong anymore, and you also know how to implement them.
Level 3 - Perhaps not reachable at all for this situation (but that's ok, not every situation has a bonus level)

Level 0 and 1 do have a trap for the uncanny valley of naming things, they may seem right and obviously are not at the same time. What exploring of level 1 unlocks is a mystified view of what's slumbering in the topic and to see the possibility of reaching level 2.

What was the level you felt comfortable with? Did you drop at some point? Are you fine with just the first three variable names and called it a day? Have I just caught your interest and you are about to dig deeper and solve the mystery? Have you maybe already solved that one?

Naming Things in Product Development

For product development domain-driven design (DDD) is a good method to aim for a ubiquitous language. Reaching there requires a conversation between stakeholders from multiple disciplines to grasp all perspectives and land on a shared language to eliminate the mental burden in your team's daily conversations and to quickly reach the point of discussion.

From the perspective of the role of a developer, there are a couple of things you want to look for when having conversations with people from other disciplines, with yourself or peer developers. The best resource to consult are domain experts and they are likely to speak a completely different language than developers are used to. This is already the first point of friction as I've realized that developers tend to name things as they appear technically. It requires time and effort to shift your mind and allow other naming methods, such as domain-driven design. In the end, we want the code to speak the ubiquitous language and not let the domain adopt a technical language.

Important for naming are objects and actions. These names are taken from the OOUX naming convention for things (nouns) and activities (verbs). While OOUX is great and I admire it for what it offers, it is not a gold standard. If you've already settled on terms for your own team, that's great. Yet for the rest of the section, I'm going to use objects and actions as described here:

• … objects (nouns) are entites/aggregates, locations (business verticals), areas (on the screen), elements/components, etc.
• … actions (verbs) are activities a stakeholder can perform directly related to an object

Unveiling, identifying, and characterizing them is a not-so-easy job. Landing at a vocabulary that is used in the specs (product), in graphic editor (design), and finally in code (development) is the goal.

Here are a couple of ideas to improve your naming game:

1. Talk and listen to designers, you may want to ask the reasons or background for something. You can also testify your assumptions, such as “do we do that, so the customer can get xyz?”. During a refinement, train yourself to understand the cues that will draw your attention. Often, there are phrases like “we do a list here, so the customer receives an explanation for xyz”. The “receives an explanation for xyz” part answers the question of what something is meant for. By doing these things you not only get a better feeling to arrive at a proper naming. A very nice side-effect is the better understanding for design and especially the design creation process.
2. Talk to P*-title positions (PM/PO/P*), to understand the different ways in which the app stakeholders manipulate these objects, their relationship to others, and which actions they are supposed to perform. P*-title positions are a great resource to understand these nuances as they know, define and understand the product.This is done as part of the ORCA process and the part described here might also be done by designers (or in combination with P*-level).
3. Full-stack pairing between FE and BE developers, to consult on objects and their technical characteristics. FE developers mostly work with a subset of the whole objects as defined in the backend or even on the database level. It is a very welcoming discussion to see how objects are represented in BE, then filtered to be transferred over the wire, consumed and processed by FE developers. Often a pairing session between BE and FE developers is fruitful to better understand the technical picture and to learn what matters on the FE and BE respectively, the what and how about the (technical) relationship.
4. Imagine a real-life situation, sometimes it’s very helpful to think of an imaginary situation, where the work of your product is done by a human. Let's say a consulting situation, where the consultant and a customer are sitting in a room together. No digital devices, everything in paper in front of them on a table.This little simulation game is very helpful to draw actions from. Especially in a non-digital situation, there is no click, no tap, no swipe a customer or consultant can do. You can directly eliminate this way of thinking. Examples:
   • The consultant would have a folder with recommendations, that can be opened.
   • The customer takes a pencil and signs a contract.
   • The customer will choose between offers lying in front of them.
5. Beyond Tellerrand, a thought experiment taking a couple of minutes, where you are exceeding the scope on purpose, pushing the boundary far further than it should be. This helps to explore the space around the actual context, will help fine-tune what is the boundary and more important, what your name WILL NOT BE. It's a way to see a sharper image of the scenery you are looking at.
6. Event storm, with your multi-disciplined team (invite domain experts!) about the subject from multiple perspectives to reach a clear picture, understand the other perspectives and be further able to share empathy with them and embody their perspective (to take a stance against yourself?).
7. Event storm with yourself, This is actually a misconception in itself but when event storming as a team is too much/not affordable, this might come in handy. When doing this on your own, you have to virtually embody other perspectives and try to understand their situation when looking at the how-to-call-it. Take it with a grain of salt.
8. Name storm (ok, I made up that one). When you understand the scenery and the only thing left is to land on a final name and you have too many candidates, throw a name storm session to decide on a final name.

With all these methods you should maintain a document about your domain terminology. Refine this document over time with even preciser descriptions and wording.

Writing specifications with this terminology will become utterly easy. Even the best specifications are not prevented from becoming outdated and the code remains a single source of truth. The holy grail a developer can reach for is to assure the code reads as the spec. Consider every location where the naming of code units does not conform to your terminology as tech debt.

Testify your existing code by reversing the approach from above. Deducting objects and actions from your code and how they are connected together, is it possible to reverse engineer the specification (for a non-developer)? Does the name of the function properly describe what it is doing or is it required to read the implementation details of it? Does the name properly express (for) what it is doing?

Grow your Repertoire

Becoming talented at naming things means you will have a big repertoire and be able to faster discard options, that you already know will not help you achieve what you are looking for. This is common amongst all talents in various disciplines. In order to stay or be talented, growing a repertoire is essential; so you can faster reach for level 2 on naming. That's why it is never a waste to pursue an idea even if it turns out to be a bad option. Following that path already has grown your repertoire over another person who took a shortcut. Don't forget to stay curious and keep up the hunger to really get to the bottom of a problem as this is the motivation for going on such a journey.

Apply Naming Things for the Biggest Impact

Naming things often requires research, failing attempts, try and error, and overall is a costly voyage. It's wise to funnel this process to control the impact.

First of all, identify people who have an interest in naming things properly and will do the required steps to land there. This is not something binary but on a scale, you can draw people towards one or the other end of the spectrum, much related is also the concept of macro and micro thinkers. I would say a person who is having a strong tendency to nail naming things is also a macro thinker. In terms of development, a macro thinker leans more on the side of architecture, developer experience, or tooling. On the other hand, micro thinkers learn more on the side of feature implementation, I have also heard the term makers for them. The team you work with clearly needs both and both need to be rewarded for what they are good at. At best, the macro thinkers supply the micro thinkers with tools and guides so they can get the work done quickly.

After identifying the right people, and knowing who belongs to the different group of thinkers, macro thinkers should be tasked with getting the naming right. There are technical things, such as namings in your tooling (design system is probably the best to name here) as well as namings in your product/domain. The former is more on a building blocks/foundation/tooling level whereas the latter is more on a conceptual level and when both are defined and their characteristics are worked out, development can happen at a fast pace as these are big piles of mental burdens keeping productivity low. Having them defined will make product development and engineering a joy to do.

I hope this article helps you understand the value and skill of naming things and hopefully you can form new strategies with your team to naming things.

Special thanks to Gabriela Ospina for editing this article and nerding out with me about naming things!

-gossi