The importance of the shared code

I remember when I was a child at school they used to talk to us about the factors of communication and the elements involved in it. The main elements were the sender (who sends the message), the receiver (who receives it), the channel (the medium in which the transmission takes place), the message (what is to be transmitted), the context (information that can help to understand the message) and the code (the means by which the message is represented).

Suppose it is Christmas time and I say to my mother on the phone “estoy contigo la noche de los regalos“ (which means “I’m with you on the night of the presents”). In this case, the sender is me, the receiver is my mother, the message is that I will be there with her on a special night, with the context she can know that I am referring to the night of December 24th (or January 5th, depending on to whom we have written the letter), the channel is the telephone and the code used is spoken Spanish.

Let’s focus on the code. My mother will be able to understand me, because I know she knows Spanish, and when I talk about the concept “noche” (“night”) we both understand the same thing. Let’s imagine I tell her in Kilingon (I assure you she doesn’t know it), which according to an online translator would be something like “jImej batlh cha’logh qoS”. The message may be there, and she can hear the words to me, but she won’t understand what I mean because we’ve missed the code.

Something that is easy for us to understand with examples like this, is not always so obvious in professional environments, where each person depending on the department or situation may have different concepts for a word. An example is the word “customer”. Depending on who you ask will give you different definitions, and we may or may not consider it a customer depending on the frequency of purchase, how long ago that does not buy, whether it is the one who pays or who receives … there are many factors that can hide different interpretations under the same word “customer”. That is why business glossaries are so important to avoid misunderstandings in organizations. But this is not where I want to point today.

In the design of IT solutions, there are many people and teams involved, and many times (too many) we take for granted that everyone understands the documents and diagrams in the same way. That is why it is good practice in organizations to define a common modeling language and use it in the definition documents, so that everyone understands the same thing. It is clear that each company can define its own language, but using a standard one will allow faster onboarding of new people and knowing that we are using something that is widely tested and accepted by other companies around the world.

Complex software diagram

By modeling language we can understand a set of rules and notations that will allow us to describe and represent technological systems in a way that allows us to communicate ideas and concepts between different teams and departments so that they all understand the same thing. This will allow us to be more efficient and effective in the development of technological designs. Although the representations can be various, the most common are diagrams in a way that allows us to visually have knowledge of the systems. Having a clear and accurate visual representation of all system components and their relationships, reduces the possibility of errors during construction and improves the quality of the final product.

There are many aspects to take into account when choosing a modeling language for the company. Some representations may be more complex than others and require a higher learning curve, some may have more tools available than others, some may have a higher usability scope (business or technical) than others, etc., so it is also important to take these topics into account when making the final choice.

Some widely used modeling languages are:

UML (Unified Modeling Language): is a visual modeling language used in software development to describe, design and document systems.

BPMN (Business Process Model and Notation): is a modeling language used in business process management to model and design workflows and business processes.

ArchiMate: is a modeling language used in enterprise architecture to model and describe the components, processes and relationships of an organization.

C4 (Context, Containers, Components, and Code): is a set of architecture diagrams that provides a pragmatic and scalable approach to modeling software architecture.

ER (Entity-Relationship): is a modeling language used in database management to represent and describe relationships between entities.

SysML (Systems Modeling Language): is a modeling language used in the design of complex systems to model and describe the behavior, structure and functionality of systems.

SDL (Specification and Description Language): is a modeling language used in systems engineering to describe the interaction between system components.

UML Diagram

These are just a few examples of modeling languages used in different application areas, although there are many more. Each has its own syntax and notations, but they all share the purpose of clearly and accurately representing the concepts and processes to be modeled.

The importance of using the same modeling language lies in its ability to improve communication between different teams. By using a common language, all team members can understand and work on the same project, regardless of their area of expertise. This avoids confusion and misunderstandings that could arise if different terminologies and notations are used to describe the same concept.

A direct derivative of this fact is that it will help reduce costs and project development time. By having a clear and accurate design, members of all teams can understand the design and different teams can identify potential problems and fix them before the implementation of the system even begins. This avoids costly errors and project delays.

The use of a common and standardized modeling language is crucial in the development of technology designs. It enables clear and effective communication between team members, improves the integration of different system components, reduces development costs and time, and improves the quality of the system design. Therefore, it is essential that technology design teams use a common, standardized and agreed-upon modeling language to ensure the success of their projects.