Why I Don’t Abbrev… How To Reduce Confusion In Software Development

A colleague shared a screenshot with me recently. Imagine being a junior dev at this company and trying to get your head around this data structure, talk about confusing! What data does the table ccex represent? Even if you did somehow know the meaning of all of these abbreviations, how would you remember all that information? If you were a new developer on the project you would have to constantly get somebody else to translate. The cmf table is a child of the ctt table which as a many-to-many relation to ccca via ccex….

Arrrrrrrrrrgh! 

This reminds me of my first job as a Software Developer in 2001. I was working on software developed in Delphi using the Borland Database Engine (BDE) as the backend. Some of the more important database tables were shared with the company’s successful FoxPro based product. Any tables that were shared with the FoxPro product had to have a name no more than 8 characters long and fields names no longer than 10 characters which had to be all caps, no spaces or special characters except underscores.

Needless to say, in that database there were tables that were named in a similar fashion to the above example. There were some very “creatively” abbreviated field names to fit into the limitations. It’s not the abbreviations that haunt me to this day, because I know they were born out of necessity. It was the inconsistency of abbreviations across the system.

It was another time. 

In the early 2000’s SQL Server hadn’t yet come into its prime and ORMs were still in their infancy. Delphi did provide components that gave direct access data tables like an in-memory data structure, but there was no abstraction of the database, and to access the data from a field you had to provide the field name as a “magic string”. There was no IntelliSense so you had to get the field name correct or Delphi would throw an EDatabaseError exception.

Whilst the Account Number field name would generally be abbreviated to ACCT_NO in the same database it was also abbreviated to:

ACCT_NUM,
ACCT_NUMB,
ACCOUNT_NO, or 
ACCOUNT.

One developer’s decision to use inconsistent abbreviations caused a cascade of extra and unnecessary mental strain for those that came after them.

Fast forward to 2019 and while the technology has changed, the same problems still exist because people are still people and they still abbreviate things because to make their life easier at that moment, or they are legacy systems which once used the restrictive old database, but have grown up into more modern databases.

So what to do?

Out of compassion for myself and my co-workers, I decided to avoid using abbreviations (where possible). So instead of the multiple options for abbreviations, ‘Account Number’ is simply ‘AccountNumber’.

I took it very seriously and made a solemn oath, and I stand by it!

“I make the choice not to abbreviate things out of compassion for those that will come after me (which could include me) so they do not have to expend precious mental energy figuring out which I abbreviations have been used where.”

I believe that good programmers make good choices. By choosing to not abbreviate things it may require slightly more keystrokes, but eliminates potential sources of ambiguity and frustration in the future. By not using abbreviations we show some compassion for the next developer who has to work on the code, keeping the mental effort needed to grasp a piece of unfamiliar code to a minimum and so they can focus on the change they need to make. Keeping in mind that the next developer could well be you!

Leave a Comment