loading...
Cover image for One Team - One Language

One Team - One Language

asarnaout profile image Ahmed Shirin Updated on ・5 min read

Don't we all just love the Grammar Police? You spend a considerate amount of time and effort expressing some opinion of yours on the internet, yet this teeny tiny grammatical error slips from your hands and BAM! Now your entire argument is deemed invalid and you're doomed to eternity for committing such an unforgivable abomination. Shame...

Fewer

Internet trolls aside...When speaking in the context of software development, one aspect is usually taken for granted, that is the eloquence and fluency of the domain specific language shared by the team. It doesn't matter if you're using English, Spanish, German or even Dothraki as long as the team is committed to using a single, unified set of terms to express their domain. Yet unfortunately, several teams seem to be very tolerant when it comes to ambiguity in their language.

A World of Dialects

Over the years, humans have managed to scatter themselves across disparate parts of the globe to form communities that evolved their own unique languages as a means of communication. Some of these languages have even evolved into different dialects that might sound highly dissimilar, which is why a US English speaker is likely to have a tough time understanding an Australian accent. In the world of software development, we can say that the same situation applies; different enterprises working in similar domains are likely to use different languages amongst them, for example in the healthcare domain, one enterprise might use "Medical Practitioner" to describe their service providers while another might simply use the term "Doctor". No rules govern the choice of one term over the other, yet the organization must aggressively enforce its own language - the Ubiquitous Language - across the entire team and refrain from allowing foreign terminology from leaking into the ranks.

In large organizations, it is pretty normal to encounter various dialects of the same language used by teams working in different contexts, for example, in a fictional e-Commerce business, the term “Order” might be used by the Purchases team to represent a request made by a Customer to buy a set of products from the website’s inventory, while the Shipping team will use the same term “Order” to represent a request sent to one of the Couriers to ship Cargo from a Warehouse located in one Zone to another. This is fine as long as each team unanimously agrees to their own definition of an “Order”.

When a rogue subset of a single team starts using its own jargon in communication with others (one prominent case is developers and business experts using different terminology in meetings), confusion will emerge and the presence of translators who understand both dialects will be necessary to bridge the gap between the team members, putting the team at risk of mistranslation as well as an unnecessary delay and inefficiency due to the newly introduced bottleneck. Moreover, from a technical point of view, it is highly likely to encounter crazy code like this: (assume a reservation context)

class ReservationService
{
    void CreateReservation()
    {
       Appointment appointment = _appointmentFactory.CreateAppointment(...);
       //It is a Reservation, but Randy likes to think of it more as an Appointment ¯\_(ツ)_/¯
    }
}

Contradictions and ambiguities in the language offer an opportunity for the team to learn more about the domain and build a deeper model. Team members should be very wary of such ambiguities and address them as soon as possible, one particular case I've came across recently while working on the Product Catalog for an e-Commerce application is that we used the terms "Vendor" and "Brand" interchangeably to denote the entities supplying our products. The team understood the importance of having a unified language and thus we discussed this confusion where good arguments were placed in favor of using either terms and at the end it was decided to use the term "Brand" in context of the Product Catalog until further insight emerges which warrants reverting back to "Vendor" or using a completely new term.

Polysemous Integration

All is well until integration between teams starts looming around. Earlier we demonstrated an example of the "Order" polyseme being used differently in Purchases and Shipping. So when these two teams start the integration process, how should contradictions be managed? Is the Shipping team’s definition of “Order” more valid than the Purchases team’s (or vice versa)? Definitely not, after all - conceptually - both of them are Orders. Should management attempt to force the two teams to completely abandon the term “Order” in favor of adopting “Purchase Order” and “Shipping Order” instead? Not a good idea and probably wouldn’t work anyway, because from the Purchases team’s point of view, an “Order” is a term that represents a single unambiguous concept in their domain and since they probably have no dependency on the concept of a Shipping Courier, therefore why would they need to distinguish their “Order” by prefixing it with the word “Purchase”?

The situation gets more complicated if the integrating teams have to share parts of their model, which necessitates a linguistic breakthrough to come up with a more mature set of vocabulary that serves both groups conveniently. However, if that's not the case, then it is best for each team to hold onto its unified vocabulary within its context, while the team members responsible for the integration process should perfect the different dialects and how to translate between them.

Beware the False Cognates

Wikipedia defines False Cognates as follows:

False cognates are pairs of words that seem to be cognates because of similar sounds and meaning, but have different etymologies.

An example of False Cognates is the Spanish word "Ropa" which could be easily confused with the English word "Rope", yet "Ropa" in Spanish means "Clothes" while the accurate Spanish equivalent of the English word "Rope" would be "Cuerda".

One particularly dangerous situation is when different members of a software team are using the same term believing it implies the same meaning then discover at a later stage that this was not the case. An example would be in a Ride Sharing application where the team uses the term "Trip" to denote their regular rides operated by their own drivers. So when they started building a new feature for supporting rides operated by Taxi/Cab drivers, the business analysts were still using the same term "Trip" for the Taxi rides, which lead the development team to - incorrectly - assume that they could reuse their "Trip" model in the new feature, however, since the team had no process of Continuous Integration, it was discovered post production that the "Trip" model held subtle assumptions which rendered it unsuitable for reuse in the new feature. Oops...

Conclusion

When it comes to the Ubiquitous Language, you have the green light to be as strict as possible to maintain its integrity. Exercise the language relentlessly and always be on the watch for any signs of confusion.

Discussion

markdown guide