Don't use acronyms while naming things : It Depends
In Clean Code universe, it is highly advised to not use acronyms while naming things. But should this be a universal law? Like most things software, it depends! Let's explore on what it depends.
There are only two hard things in Computer Science: cache invalidation and naming things.
— Phil Karlton
What is the goal of naming things in software and naming them “right”? — To reveal the clear intent. By intent, we mean the name of the variable, or function, or module etc., correctly represents its purpose. A name which reveals its intent clearly reduces cognitive load on developers’ minds.
Naturally, naming is neither a one step process nor an individual’s exercise. It is a team game and as @arlobelshee points out it is an iterative process, with each iteration your naming approaches a supple design (DDD).
The intent, however, is not supposed to be just clear to developers, but to the entire team. A typical team would be cross functional — it would not just have engineers, but also domain experts, marketing, and product folks. The entire team should use one language — the ubiquitous language.
In one of the large scale projects which I was a part of, we were developing a business “proposal calculator” for a large bank. The “proposal calculator” was supposed to run 1000s of calculations and tell whether a proposed corporate deal was beneficial for the bank or not. Long story short, naturally there were a lot of financial terms that were part of daily conversations. PnL, collaterals, amortisation to name a few.
A lot of such terms were used as their acronyms, instead of their full forms, by the bankers (the domain folks) in their own conversations and also when they referred to such calculations to us (the developers). So they would not say “Profit and Loss”, but “PnL”. They would not say “Return on Risk Weighted Assets”, but “RoRWA” (pronounced row-rah).
Early in our design phase we took a conscious decision of going ahead and using the acronyms themselves instead of their long forms. In hindsight it was a good judgement call by the team, especially when all literature around clean code was advising otherwise. The literature would advise to use pronounceable names and only use acronyms when they were widely known — highly debatable and very contextual. Turns out RoRWA wasn’t that widely known amongst developers atleast.
Imagine if we had not — When developers would have had conversations amongst themselves, we would use “Profit and Loss”. But whenever we would be in meetings with the domain folks, we would only hear “PnL”. Imagine the fiasco when “Return on Risk Weighted Assets” would come into such conversations. Moreover, our use-cases which were written primarily by domain people would only contain such acronyms, not their full forms. Not only we would have added unwanted cognitive load upon ourselves, since we would always be playing this ontology game of mapping the acronyms with their full forms, but we would have also made the conversations difficult, because the domain folks were more comfortable with acronyms themselves.
It was difficult to onboard new developers at first. Imagine yourself hearing PnL vs hearing “Profit and Loss”, especially when you do that have acquaintance with financial terms. Your mind can make some sense out of “Profit and Loss” in the very first go — because basic mathematics — but won’t comprehend PnL naturally. This was the case with some common-sensical terms, but “Return on Risk Weighted Assets” would still not make sense. The team came up with a glossary. It helped heaps, not just for the new developers, but also for the ones who had been on the project for considerable amount of time.
We made a conscious effort to keep the glossary as a living document — forever changing and changing as frequently as was the need. We would refer to it whenever we had a doubt, added questions to it and added lots of examples. We also shared this glossary with the bankers and they generously added enough information to it. At times they added more information — just to make us, the financial-rookies understand — than was required to be able to successfully model it in our code. But it eventually gave us the comfort and cognitive ease which we needed, but didn’t know we did.
Remember, DDD is a team activity!