Having a ubiquitous language within your organization means that when someone on the developer team refers to “the foo bar,” the people on the design team, the service team, and all the other teams, know exactly what they mean. Although a general understanding of the term is the most important aspect of ubiquitous language, we’d recommend not using terms like “the foo bar,” and rather applying principles of domain-driven design to your naming system so that your glossary actually makes sense in the real world! Join us today as we share our experiences of dealing with ubiquitous and non-ubiquitous language in our working environments, and the importance of bringing up this topic as early on in any job as possible.
Key Points From This Episode:
{{addCallout()}}
Transcript for Episode 240. Ubiquitous Language
[INTRODUCTION]
[0:00:01.9] MN: Hello and welcome to The Rabbit Hole, the definitive developer’s podcast living large in New York. Hi, I’m rabbit number one, Michael Nunez. We have rabbit number two.
[0:00:09.3] DA: Dave Anderson.
[0:00:10.6] MN: And rabbit number three.
[0:00:12.2] SC: Sophie Creutz.
[0:00:13.3] MN: Today, we’ll be talking about Ubiquitous Language.
[0:00:17.6] SC: Ubiquitous.
[0:00:19.1] DA: It’s in the air, can you – it’s everywhere.
[0:00:21.7] SC: It’s everywhere.
[0:00:22.9] MN: Is it?
[0:00:23.6] DA: It’s permeating, yeah, it’s not the smell of the construction.
[0:00:27.6] MN: What would you call that? What would you call that smell in the air?
[0:00:32.5] DA: This is ubiquitous but it’s not a language, it’s a smell.
[0:00:36.8] SC: Is it the building thing service or is it the wake me up early and make me angry service?
[0:00:43.2] DA: Yeah, but ubiquitous language is nothing to be angry about. It’s a really great tool that you can use with your team, your technical team, your non-technical team, like in design, to be able to talk with each other.
[0:01:01.4] SC: Yeah, I guess that’s the idea, right? It’s that there’s this Venn diagram in between different stakeholders and your system naming conventions because they ideally correspond to real world concepts, they fall into the middle of that Venn diagram and everybody understands the naming convention.
[0:01:17.8] MN: Yeah, I mean, it’s not like – you know, I think of a ubiquitous thing as not like a tangible thing, more like a concept that everyone should have in their brain before they come up with a particular pieces or language or words that coincide within the two sides of that Venn diagram. I know that a lot of the times, I’ve worked at a place where this was like, really difficult but there was a glossary that existed but it was just like, “Oh, when the domain expert says this, they actually mean this in the system,” which is like very difficult.
[0:01:57.3] SC: Actually, a translation.
[0:01:58.7] DA: Wow, yeah.
[0:01:59.5] MN: It was more of a translation more than a glossary of the words that domain experts would say and that is the opposite of what ubiquitous language is trying to do with the systems in place of keeping the glossary and stuff like that.
[0:02:16.1] DA: Yeah, I guess – it sounded like you were pretty close there. You had the glossary and you both had language so you could communicate but I think, it sounds like the thing that was missing was the most important part of ubiquitous language is that like, there’s a conversation between all the people who need to use it and they decide what language is going to be used so that you don’t need a translation layer, you just need to have an idea.
[0:02:45.1] MN: Right. Yeah, it was very, very difficult at some point. We were like, “We should change some of the things in our systems because they’re saying things and we shouldn’t do this heavy translation portion to understand something. We should just be using their words per se or talk about why, if we think their words don’t make any sense to us, why that’s the case and then come up with the consensus versus a one-way directional conversational flow.”
[0:03:14.9] SC: Do you think there was something in particular that kept you from aligning on ubiquitous terms?
[0:03:23.5] MN: I can’t recall right now at the moment but it was more about not having the time to rename certain things or like the system was pretty legacy at that point so for us to do a renaming of sorts would have been hair pulling. I think that was like in mind like, “Hey, this is a lot of overhead that we should not deal with and this is something that we should focus when we extend the application or start a Greenfield project that will change the legacy system essentially.”
[0:03:59.0] DA: Yeah, I guess that’s a great point. The momentum of the current system as it is, can make it really hard to kind of adopt that. If you have a really powerful editor, like IntelliJ has wonderful refactoring tools. I feel like using those tools made it easier for me, on different teams that I’ve been on, to actually adopt ubiquitous language because in any case, it’s going to evolve over time and your understanding will become more clear.
I remember on one project that we were working on, we were thinking about this from the start so we generally had a pretty good language and a good way to communicate about it. I mean, it was object oriented, we were doing Go. It was in the network domain but the thing that let us be flexible with that was being able to refactor.
We would have this concept of a probe and then the probe would do something over the network but it could do it different ways like a DNS probe or TCP probe or HTP probe, there are all these different ways that it could do that but kind of having that flexibility to refactor because I don’t think we started with probe, I think it was just like DNS thing, you know?
[0:05:28.8] SC: Right. Yeah, I guess if you said that in a refinement meaning or something, not everyone would potentially know what that was, right? It sounds like you established a glossary of terms and made sense to all stakeholders, is that right?
[0:05:44.2] DA: Yeah, we tried to have a sketch as the system was evolving. How it looked and how we were trying to get it to look really, when we were kind of evolving the language. “Okay, we can change these things in this way,” and then that kind of facilitated the refactor so that it ended up with a more consistent language
[0:06:07.8] SC: Yeah. I’m curious, just for a thought exercise, could we come up with an example of the opposite of ubiquitous language? Kind of like we were doing when we were thinking about the construction, right? What’s something you could call a concept or a service or a method, a function, that would not be ubiquitous?
[0:06:26.2] DA: I definitely had a problem or a challenge working on the frontend, talking to designers where they would provide us with mock ups and in the mock ups, they would indicate which colors they were using or what the components were but the components, similar to what Mike was saying earlier where you have to have this translation layer.
We didn’t even have a glossary as a translation layer and they’d be like, “Okay, this is red 30, you use red 30 and there’s some hex code associated with it,” but if you look in the code, there’s no such thing as a red 30. It is light red in the code but you have to search by the hex code.
[0:07:09.9] SC: Oh, search the hex code, yeah, okay.
[0:07:12.9] DA: If I’m able to have that agreement between the designer, if they say something and I know what it is and I can just go and type it into the computer then that’s kind of amazing. It helps you build the mental model a little bit better and that extends to components too, like in a design system they may have a primary button but some people are calling it CTA button, then you have to make sure that you know what that means. Pairing button is like, “Okay, that’s the bright red button that people can click on,” it’s not always a CTA but maybe in one particular case, it’s a CTA.
[0:07:46.2] SC: Well, I think you’re bringing up another good point here too, right, it’s that like, it’s not necessarily just about, “Let’s name it something that everybody agrees on.” You could call it, “My favorite button,” or, “The button that does the thing,” but more so that you have to agree on it but that also it has to describe what it is, how you made it.
[0:08:03.7] DA: Right, yeah, exactly. If one team’s calling it the red button and then the other team is calling it a primary button or a CTA button then it doesn’t really help.
[0:08:16.2] SC: Yeah, it's part of the domain driven design here too, right? That you have to name it in a way that describes what it is or what it does?
[0:08:24.9] DA: Yeah, domain driven design is kind of traditionally a toolkit for object oriented programming but it can be applied to any kind of programming so there’s a kind of, the objects are the nouns that act on each other with their methods, which are verbs. If you like drawing a picture of how all these things come together, then you can have the boxes be the objects and the lines be the verbs of how they stick together and like the DNS probe can –
[0:09:00.3] SC: The DNS probe grows.
[0:09:01.2] DA: Yeah, ask the DNS client, “Hey, what is the statistics for this thing? How many seconds does it take?”
[0:09:10.7] SC: Yeah.
[0:09:10.4] MN: Yeah and I always, you know, there’s that idea that naming things is hard in programming and it’s really great to lean on something like domain driven design because it gives you a system of things so that you can name your objects or classes, that’s more real world per se versus being caught in the, “Oh man, what should I name this thing?” and it’s like, “No, name it what it really is and what it does and start there and then make sure that that is what your team is calling it and what the business domain individuals are calling it as well.”
[0:09:48.2] DA: Right, I guess it’s like if naming things is hard and everyone is solving that problem by themselves, like each time that they do it, each time they work on a problem then it’s going to be even harder because when you go from one part of the area that Bobby made to the other side of the program that John made, then like you won’t be able to understand how to get those things to hook up.
[0:10:14.0] SC: Yes, well you might have like in one place it’s called a guest and then somewhere else it’s called a customer and then somewhere else it’s called a user and you know, someone coming into this codebase, they might not know that these things actually are supposed to be the same concept.
[0:10:27.2] MN: Yeah.
[0:10:27.8] DA: Yeah, I mean that’s like that’s the absolute worst case scenario of it where like not only is like the business people talking about it in a different way or like your product and design people talking about it in a different way but like the engineers on the different parts of the system are also talking about it in different ways.
[0:10:43.5] SC: Yeah, like I said, that’s maybe the time to take a step back and try to codify that glossary.
[0:10:50.1] MN: Yeah and glossaries are a thing that exist that teams have and I guess this is to ensure that they’re defining the words that are used, not a translation, like I mentioned earlier and it’s just like, you know, making sure everyone is at the same page of what is a coupon, for example, and what is customer versus a guest and if there are differences then the glossary would be able to separate that and the language that’s used within conversations, within IPM and stuff like that are used just like they would be in the glossary.
I do have a question, I know that domain driven design talks about a domain expert a lot of the times, who on your team would be considered a domain expert?
[0:11:40.2] SC: Yeah, that’s a good question. I was thinking about that too because it seems like the glossary, the terms that you chose, ideally should reflect domain language as well. I guess that could mean it’s whoever knows that domain language the best, right? If it’s a music app, maybe someone who really knows the music industry. If it’s a restaurant app, someone who really knows the restaurant industry, you know? That kind of thing.
[0:12:03.2] DA: Right, yeah. It could be either your product manager or a stakeholder or a customer relations person, like someone who is speaking the language.
[0:12:16.0] SC: Knows how to talk the talk.
[0:12:17.8] DA: Talk the talk and then the developers are there to walk the walk I guess, maybe or maybe everyone walks the walk, I don’t know how works.
[0:12:26.8] MN: Yeah.
[0:12:27.6] SC: Well, ubiquitously, we’re all talking the talk.
[0:12:30.8] DA: That’s true, yes. It’s the language. There’s no walking involved here yet I guess.
[0:12:36.1] MN: So you know, I implore the listeners to kind of look at their systems that they’re currently working on and see, are they following any ubiquitous language or are they breaking the rules of that, right? Because I think like I can’t remember and pinpoint the start of my career where I started thinking in this particular way but I knew that it made sense to before I picked up domain driven design and then I read the concepts of ubiquitous language.
I guess I’ll ask, when do you start to teach like that concept? When do you start picking up ubiquitous language?
[0:13:20.6] SC: Day one.
[0:13:21.5] MN: Yeah, because I’ll mention I have a friend who, you know, who is learning how to program and I can see that sometimes like variable names can be just like X or B and it’s just like a placeholder for this leak code kind of problem. I know this is not the same as an actual application but I try to tell them, “Hey, no, no, you should actually try and name this variable. What is this variable doing or what is it?” It’s just like, “Bro, it’s K. It’s the letter K and that’s it and we’re good.”
[0:13:54.1] SC: Isn’t it obvious?
[0:13:54.9] MN: Yeah, I’m just going to use it as K and that’s what we’re going to do.
[0:13:59.1] DA: Right. Yeah, I mean, I think that makes sense though because if you are just learning programming, it is hard to practice multiple things at once. It’s like, I’m just trying to get this four loop thing under control.
[0:14:14.8] MN: Under control.
[0:14:16.4] DA: Yeah but I think it’s a great thing to think about and exercise as a muscle but they might have to think about it differently or like maybe they can practice it by reading code that is designed in a more clean way or taking code that they’ve written earlier and try to just rename things so that it makes more sense. You’re not thinking about how to do the code and make it work. It already works, you just kind of have to give things better names.
[0:14:49.5] MN: Right.
[0:14:50.4] SC: Yeah, maybe it could be a situation where okay, first it’s deemed K and then you write this four loop, you get that under control and then you come back and you think about, “Okay, how do I iterate on this naming? How do I name something that now is more descriptive?”
[0:15:05.2] DA: Yeah, that’s true. I feel like that happens a lot where you’re trying to name a class or a method and it’s like this thing is a foo right now.
[0:15:15.1] SC: It does the thing, it’s a doer.
[0:15:17.2] DA: It’s a thing doer and then it has a method, do thing.
[0:15:23.1] MN: Yes.
[0:15:23.1] SC: New thing, do the other thing.
[0:15:26.0] MN: Yeah, naming is hard and we should all lean into ubiquitous language to help us name our variables and classes and objects because sometimes it’s got to be a foo bar.
[0:15:41.4] DA: But then once you’re done, you commit. It works and you commit and then you can rename it to something better or like you know, get a pair, get some other eyes, talk, have a conversation with the product people, the designers and bring people together and talk about what it is and how it fits in the big picture.
[0:16:01.5] SC: Yeah, I almost wonder if it’s the chicken or the egg kind of thing, right? You could name it foo bar and then you write it and it does the thing and it works and the tests pass but what if like you all agreed on the name from the beginning? Maybe that would inform how you wrote your code and perhaps that is part of the point of ubiquitous language and domain driven design.
[0:16:21.5] DA: Yeah, there are tools that you can use too, to try and tease this out in more of a fully formed kind of way. There’s this exercise called event storming, which is maybe a longer topic that we don’t have time to go into right now but a tale for another day.
[0:16:41.9] SC: Stay tuned.
[0:16:42.4] DA: Stay tuned.
[0:16:43.6] MN: Stay tuned.
[0:16:45.1] DA: Yeah, you could like work together with all of the people who are involved and have the knowledge and come up with the good names and the good language that will help you build things out.
[0:16:57.3] SC: Right, yeah. This event storm, I think it’s going to be Jasper.
[0:17:02.0] MN: Oh boy. Oh man, I will say on a note that, understand that the conversation on ubiquitous language and creating the glossary are coming up with the language used by both parties, so domain and the technical experts, is a conversation that happens throughout the existence of you building the application. It’s not like you have it once and then you go back and the glossary is finalized and everything is fine.
Know that you will need to go and reach out to the domain expert to ask questions and ensure that what you’re writing in the system is very similar to the real world application of the application you’re building and know that it’s just an ongoing conversation that will continue to happen as you are extending the app.
You know, look at your app and reflect and see if you’re following the principles of ubiquitous language and if not, then change all your foo bars into domain related names because I think it’s important for you to go and find and look up and everyone speak in the same terms so you don’t have this mental overhead of language when you’re building your app.
[END OF INTERVIEW]
[0:18:18.6] MN: Follow us now on Twitter @radiofreerabbit so we can keep the conversation going. Like what you hear? Give us a five star review and help developers just like you find their way into The Rabbit Hole and never miss an episode, subscribe now however you listen to your favorite podcast. On behalf of our producer extraordinaire, William Jeffries and my amazing co-host, Dave Anderson and me, your host, Michael Nunez, thanks for listening to The Rabbit Hole.
[END]
Links and Resources:
