Submitting your vote...
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 qucik 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?
If your programmers editor recognizes the name after 3 of 4 characters the length is no point. Stays the readability.
And your examples are clear.
Regards,
Daniel
However, some variable names are so well known, that there's no point in making them longer.
E.g. everybody uses $i and $j for iterations. What point would be using $iterator, $innerIterator?
Other, $res, it's clear that it means result set (or result whatever). Just in case you have multiple $res' I'd use somethink more clarifying.
as much as I agree to most of your posts I am of other opinion this time.
"Classic computer science does not really tell us what to use."
That might be correct, but modern computer science _does_ so. Things were different in the past, but with contemporary tools most of the arguments against full method/variable names are obsolete:
> the programmer do not have to pay lots
> of attention to proper letter case
IMO programmers _should_ be much more aware of proper typing anyways.
> it simply faster to type short word
Code gets written less than it is read. So we should focus on better readability first of all.
> line length is shorter
If a line is really long, it's probably not a problem caused by long variable names but rather by put-all-code-in-one-line or nest-as-many-conditions-as-possible fanatics ;)
> it is easier to catch $res than $mySqlResource
I agree. res is easier to catch. But "mySqlResource" or simple "resource" is just easier to understand (unless you're used to res since years, which shouldn't be assumed). Actually res is a very good example for a common misunderstanding as lot's of programmers understand it as "result" which is wrong.
Mind that acronyms are a completely different thing. I find "DB" for "database" perfectly readable.
Concerning the $res = some DB stuff: Each time I read this, I wonder whether $res means "result" or "ressource" (meaning: I don't know whether I can be sure of the type of the variable). I think this isn't used consistently in the TYPO3 core.
To keep lines short, I try to reduce the nesting level (which also improves readability). In addition, I try to shorten compound variable and function names by putting them in the proper context: For example, my_div::setFrontEndUserName() would become my_frontEndUser::setName().
Any capable programmer worth his grain of salt would heavily object from naming a loop counter anything else than "$i" in the first place if there's no other sematice concern to be fulfilled.
One of the key annoyances in Java, for instance, is the verbiage it throws on you. PHP has a little more degrees of freedom, stemming from its tradition of a quick'n'dirty scripting langauge - we shouldn't lose this heritage altogether.