Clarity in the Workplace

Nomenclature is important. When we discuss events, situations or ideas, it is really important that we are able to identify what we are talking about. Often enough, I find myself left out of a conversation because I missed some abbreviation or can't understand whatever sub-vernacular is being used. That is fine pretty much everywhere but the workplace.

If I am out in public or hanging out with some friends and I'm lost because I'm simply out of the loop, fine. I accept that. I probably don't need to know or understand what is going on. In the workplace, it's pretty much the exact opposite. Not only does it benefit me to know, but its my job to know what is going on in the world around me. Even as a developer, islanding is not totally an option. Sure, you can submerge for a while and peek through the periscope now and then, but it doesn't get you all the way there.

The company I work for is going through a bit of a metamorphosis right now in terms of how it handles code. We're moving away from the old monolithic approach to the newer methodology of microservices. More things concerned about less data, rather than less things concerned about more. One real big part of this is naming - and of course, since we're all hipster developers, we come up with names that only tangentially make sense. Y'know, like when you pick some single word that kinda describes what your program does and add .js to the end of it. Perfect.

Here it's worth noting that I'm probably the biggest culprit of this, especially internally to the company.

Naming Patterns

One of the primary issues we are facing is that people simply don't understand what does what. The biggest offender we have is a combination of two repositories. One is a library, and the other consumes that library. The issue we see is that the consuming repository, which is a service, is named the same as the library but with -service plopped on the end of it.


This has lead to hours of engineering loss due to misunderstanding. We've had meetings to discuss what the difference is between the two. Were they named completely differently, this would have likely never been an issue, or at least would have been much less of one.

When naming your repositories, name them something clear and concise. If you are titling your package/project, pick something at least understandable. Otherwise, consider the less sexy, but more straightforward option of naming it what it does. thing-doer.


Internal office lingo is unavoidable. Acronyms and titles for things that have no real title on the outside just happen. The issue to solve there is keeping the lingo consistent across teams, and oh man, departments.

Consider the following: you and your team are working on a front end component for on-boarding users. During all of the development, you refer to it as 'first time experience' or 'fte'. Later on, you're in a meeting discussing test automation for your new component. The quality engineers are talking about 'the welcome page'.

Well, that's confusing. Here, I thought we were talking about First Time Experience. What is this 'Welcome Page' you speak of?

Right there is the disconnect. Two teams, one subject, two names. The main thing to keep in mind here is that not everyone is talking about what you are working on day-to-day and using the same lingo as you. Consider the other people who may see or work on your code, and keep in mind that when you were first presented with the concept, you came up with your own way of referring to it. They'll do just the same unless it is documented somewhere easy to see.

Keeping it real

When it gets to the point that your GTM MVP of the new stinkopants plugin for the TRL page of sp-service is on the fritz, maybe you should consider making your life and the life of those you work with easier and spell some stuff out.

Like really, why the hell is it called cucumber?