Home » Avoid… » Shortenened names

Shortenened names

Abstract

Shortened identifiers (for example – the names of classes, members and variables) are artificially shortened words. For example: cust, qty, param, cnt, mod, auth, lang. These stand probably for: customer, quantity, parameter, count, mode, authentication, language. Shortened names should be avoided in general, especially in the code written in modern object-oriented languages. Most languages don’t have the strict limitations which some programming languages had 40 or 50 years ago. There is no plausible reason (anymore) for not using the proper real words, unless your want to make the code not easily understandable and make fellow developers feel upset, frustrated and angry. Cnt, qty, param, and so on – these are not the real words. They distort the understanding of code and disturb the human beings who have to read the code.

Historical background

Many developers learned programming either in the dark ages of computer technologies (which were only few decades ago) or were teached by the guys from the dark ages, carrying a lot of legacy from these times. Back in the days some languages had limitations on variable names. For instance, Fortran 66 allowed identifiers with length up to 6 characters. There were no IDEs (and of course no intellisence either). Text editors in DOS-like-systems were the only tools for coding. Hard drives were a few megabytes large, RAM was measured in kilobytes, displays were small cubes with a resolution of 640×480 (or even less) and all of that was expensive as hell. So, the code was very much like algebra, for example “int fwr = (a + bt) / q;” because of the programming language or for the sake of saving bits and bytes or in order to simply make it fit to the tiny low-resolution screen.

This all is since years not the case anymore. We have terrabytes of disk space, gigabytes of RAM, double screens sized over 20″ each, and programming languages with almost unlimited naming possibilities. At the end, few bytes more or less usually make no difference at all. But many developers (especially the older ones) stick to these obsolete naming practices. And even more developers of the next generations learn from them, copying and adopting their habits.

“This is not a word”

You probably know this argument from Scrabble.

Wh wld y wrt smth lk tht whn y cn us prop lang?
(Why would you write something like that when you can use proper language)

The sentence above is almost unreadable. What would you say if you’ll read a book written like that? Would you continue reading? Of course no. And therefore, if your programming language does not have limitations on naming, JUST DON’T CUT THE WORDS. Write it in the way that everyone will understand it easily. Saving a couple of letters won’t do any good to anyone. It won’t save much of your time either. When you start to type a name while coding, you usually type only the first letters anyway, and autocomplete does the rest. Some developers actually even try to justify their cryptic shortened names with an argument that shortening makes names shorter. Yes, you’ll get shorter name, but if the name is not immediately understandable by everyone, it doesn’t matter how short or long it is. It has to speak for itself and should never require “decryption” to the real language.

Note: you also wouldn’t read a book which has mixed languages, for example English and German or French and English. If you read a book in English, you expect it to be written in correct English, forgiving a little bit of incorrectness or stylistic flaws to not-native speakers.

Even if someone thinks that, for example, “rep” stands obviously for “repository”, this is not true for the others. “Rep” could also mean replacement, reputation, repeater, rejected project or whatever else. Depending on your domain it could be even refined powder or reptiles. By using “rep” as a name you force other developers to guess what it is.

Googling for source codes will deliver numerous results with shortened names. I took a random top result on google which offered more than enough examples for this article – this one. Here are only few lines picked from different methods. You can only try to guess what did the developer mean by all these cryptic names:
m_cal = cal;
selItem = this.listView.Items[sel];
info[3] = cbf.Company;
cbf.Name = subItem.Text;
cbf = this.GetCurrentCBF();

…and so on. What is “cal”? Calories? Calculator? sel = sell, select, or something else? And what is this CBF??! The only way to avoid guessing is to name things properly, using complete explicit real words, in whatever naming convention asCamelCase, OR_LIKE_THIS, OrLikeThat since programming languages don’t allow blanks in the names (yet).

Empra Study

Johannes Hofmeister from Heidelberg University (Germany) did an “Empra Study” in 2013, in which he compared how fast (and whether at all) the developers will find bugs in the code which uses shortened names vs. explicit “real word” names. It took 10 to 25% less time to find bugs in the code with explicit names (customer, request, etc.) vs. shortened names (c/cust, r/req). Details can be found here (in German language).

This study proved that shortened names are less understandable. This actually beats all other arguments which are not backed with studies.

How to keep the names short without shortening

Short names in code are actually very good but only if they are precise. And they must be precise, without parasite words like “Data” or “Manager” which are there but don’t have any value in describing what’s behind the name. For German speakers I want to recommend an article by Johannes Hofmeister about such “Weasel Words” published in German Dotnetpro magazine (04.2012). Here is his blog entry with a link to an article.

The hatter’s signboard

In order to demonstrate how to keep the names short and precise, I would like to share a story which I’ve learned from the “Refactoring to patterns” book by Joshua Kerievsky. This was originally written by Thomas Jefferson about Benjamin Franklin (source):


“I have made it a rule,” said he, “whenever in my power, to avoid becoming the draughtsman of papers to be reviewed by a public body. I took my lesson from an incident which I will relate to you. When I was a journeyman printer, one of my companions, an apprentice hatter, having served out his time, was about to open shop for himself. His first concern was to have a handsome sign- board, with a proper inscription. He composed it in these words,

‘John Thompson, Hatter, makes and sells hats for ready money,’ with a figure of a hat subjoined;

but he thought he would submit it to his friends for their amendments.

The first he showed it to thought the word ‘Hatter’ tautologous, because followed by the words ‘makes hats,’ which show he was a hatter. It was struck out.

The next observed that the word ‘makes’ might as well be omitted, because his customers would not care who made the hats. If good and to their mind, they would buy, by whomsoever made. He struck it out.

A third said he thought the words ‘for ready money’ were useless as it was not the custom of the place to sell on credit. Every one who purchased expected to pay.

 
John Thompson, Hatter, makes and sells hats for ready money
They were parted with, and the inscription now stood, ‘John Thompson sells hats.’ ‘Sells hats,’ says his next friend! Why nobody will expect you to give them away, what then is the use of that word? It was stricken out, and ‘hats’ followed it, the rather as there was one painted on the board.

So the inscription was reduced ultimately to ‘John Thompson’ with the figure of a hat subjoined.”

 
John Thompson

Short is good, but not too short, please

In this old blog post Andy Lester declared the “The world’s two worst variable names”:

  1. data
  2. data2

In a more specific example he demonstrated the following “coding horror”:

$total = $price * $qty;
$total2 = $total - $discount;
$total2 += $total * $taxrate;

$total3 = $purchase_order_value + $available_credit;
if ( $total2 < $total3 ) {
print "You can't afford this order.";
}

And then he refactored the code by simply doing search-and-replace for variable names:

$order_total = $price * $qty;
$payable_total = $order_total - $discount;
$payable_total += $payable_total * $taxrate;

$available_funds = $purchase_order_value + $availble_credit;
if ( $payable_total < $available_funds ) {
print "You can't afford this order.";
}

By increasing the length of each line by only few characters, he made the code much better understandable. One more thing to do is renaming “$qty” to “$quantity” or “$amount”. Because we don’t to force someone who reads this code to play the guess-the-word-game again – quantity?… quality?… qwerty keyboard layout perhaps…?!

Many today’s IDEs have renaming as a built-in feature, you don’t even need to do search and replace – use the IDE to rename safely and comfortably.

Exceptions

Of course there always can be few exceptions, for good reasons. I feel that following shortened names or abbreviations are still OK:

  • commonly used abbreviations: xml, html, sql, dto
  • words which you shorten when you pronounce them in a sentence, like “info”
  • any word forms and artificial words from the specific domain of your project, as long as you use them when communicating to business people

All exceptions have one in common – you would use these, even if these are not the real words, in a project-related talk with business or technical people. I mean, as long as you pronounce xml as “iks-em-el” and not as “extended markup language”, it’s ok to use “xml” as a name or as a part of a name in your code.

Additionally, in C# I often use a variable “x” in lambda expressions, for example:
customers.Select(x => x.Address)
I think that it’s OK, because first – the context here is “customers” – this is clear because the word “customers” stays in the same line before the lambda expression. Second – it feels more like mathematical equation with x where x = customer. Using the word “customer” instead of “x” would include it multiple times in one line:
customers.Select(customer => customer.Address)

Image Sources

Thanks for the picture:

Level Up Code, February/March 2014


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: