Aug 18, 2008

Should abbreviations be used in the code?

Two times in the past month I came to the same question: should abbreviations be used in the code or not? In this article I am trying to give my answer to the question.
DEFINTION

Wikipedia defines abbreviation as:
An abbreviation (from Latin brevis "short" is a shortened form of a word or phrase. Usually, but not always, it consists of a letter or group of letters taken from the word or phrase. For example, the word "abbreviation" can itself be represented by the abbreviation "abbr." or "abbrev."
So the question becomes: should code contain

$mySqlResultSet = $GLOBALS['TYPO3_DB']->exec_SELECTquery(...);

or can be as simple as

$res = $GLOBALS['TYPO3_DB']->exec_SELECTquery(...);

The thoughts

Both statements above are valid. The only difference is that second one is shorter.

Classic computer science does not really tell us what to use. During education theory indirectly teaches us to use full (unabbreviated) names. Modern books do not use abbreviations in examples.

On the other hand, practical lesson often use abbreviations where it makes sense. This shortens time to write code because:
  • the programmer do not have to pay lots of attention to proper letter case
  • it is less likely to misspell a short word than a long one
  • it simply faster to type short word
Using abbreviations often (notice italics!) makes code more readable:
line length is shorter
it is easier to catch $res than $mySqlResource (just remember how much longer it took you to scan the second variable name on this line)

However not every abbreviation is good. Consider the example from above rewritten as:

$r = $GLOBALS['TYPO3_DB']->exec_SELECTquery(...);

What does that '$r' is supposed to mean? Retraction? Reactivity? Reactivation? Resemblance? Not clear. Meeting this variable in the rest of the code will force you to remember its meaning. On the other hand, $res is much easier to remember as "resultset" or simply "result" (depends on your preferences).

The rules

The above said leads to the rules.

The first rule says that using abbreviations in the code should be allowed.

The second rule says that abbreviations should be good enough to allow unconscious and immediate understanding of their meaning.
THE ADVICE

There are several techniques that I personally employ when choosing names for the variables and methods.

The name should be short. As shown above, long names have only disadvantages.

On the other hand names should not be too short. They should look natural. For example, trying to shorten "makeList" to "makeLst" or "mkLst" (or even "mkLs") creates exactly the opposite to the immediate understanding of the meaning. (Using such names in the code probably comes from using too much Unix command line. Remember "vi", "ls", "rm", etc? They were made to be short and quick to type, not to be readable! The code is opposite, it must be readable.)

Another example. Consider the function named "checkAuthenticationService". This is pretty long one. While it can be kept as is, I see no problem in making it "checkAuthService". That one is shorter, and eye catches it at a glance. The meaning is preserved, you make less misspellings, etc. There are only advantages.

A special word about constants. Typically I used abbreviations in constants until recently. For example:

const UT_MODERATOR = 3;

As was pointed to me by Ingo Renner, this is not too clear. While it is clear to me what "UT_" means, is it clear to you? After some thinking you may guess that it is probably "user type". After Ingo's advice I changed my habits to using this:

const USERTYPE_MODERATOR = 3;

and I find it much better for understanding of my own code.

Conclusion

Personally I find abbreviations in the code useful. They speed up writing and make less mistakes. However abbreviations should be good. Using good abbreviations in the code makes is better looking and less error prone.

What do you think?

No comments:

Post a Comment