How Variable Naming Can Significantly Impact Your Teams Productivity
What does kunnr mean? Anybody? If you’ve worked with SAP than you might know but to everyone else good luck. What about rqnb? Does it mean anything to you? Isn’t it obvious to you that rqnb represents a request number? Seriously though, why do people name their variables so cryptically?
Think about it a little, how much easier would the code be if the variable was named requestNumber instead of rqnb? And for those of you who think it will save a few keystrokes, hence make your typing faster, remember that each time you use the variable you have to remember how to abbreviate it. With one variable it’s not so bad, but when you have dozens, you’re always looking up the different variable names.
Still don’t believe me that it makes a large difference, tell me what the code example below does (ignoring all exception handling):
public static void chPd(uId, oP, nP)
{
Usr u = UsrDB.getPrf(uId);
if(cfPd(oP))
u.chPd(oP, nP));
}
You might have a chance with that one because it’s similar to the Unix/Linux command line tools. But what about the following more complex case:
function clcMtPy($mtAmt, $ct, $intRt, $nPt)
{
$mInt = clcMtInt($ct, $intRt);
$mPym = $mtAmt * $mInt;
if($mPym > 0)
$mPym = $mPym / (1 - pow((1 + $mInt), - ($nPt)));
return $mPym;
}
How easy was that to read? You probably didn’t get the meaning of what’s happening in the first pass, or even the nth pass. And nor should you. But that’s how a lot of code is written. What if instead it was written as:
function calculateMonthlyPayment($mortgageAmount, $country, $interestRate, $numberOfPayments)
{
$monthlyInterest = monthlyInterest($country, $interestRate);
$monthlyPayment = $mortgageAmount * $monthlyInterest;
if($monthlyPayment > 0)
$monthlyPayment = $monthlyPayment / (1 - pow((1 + $monthlyInterest), - ($numberOfPayments)));
return $monthlyPayment;
}
How much easier is that to understand? Sure in the cryptic example, once you get a good handle on what’s going on it makes sense, but how long did it take compared to the last example. And How many times did you have to re-remember which variable represented what?
Isn’t the last example much much friendlier? Couldn’t almost anyone jump in and understand right away. How much time is spent in the first two examples just understanding what’s what? And that’s with abbreviated names, what if I had just used one letter variables? Don’t get me started on that. Ever try to search for instances of a variable that’s one letter? Try searching for the variable “u” (used in the first example) on this webpage. How many hits did you get before you found it? Good luck with that!
By the way, this code is actually a real life snippet of code from our free real estate analyzer. Although our main LandlordMax application is written in Java (Swing), the free real estate property analyzer is written in PHP. Not that it really matters, this code isn’t really language dependent. (And please note that I’ve removed all code dealing with currency and doubles for clarity).
In any case, all this to say be careful when you name your variables. Don’t think in the now, think beyond. Think about tomorow and the next person. Make everyone’s lives easier. Yes it might make your code more verbose, but it also makes it readable! It’s well worth the cost.
· August 14th, 2008 · 8:00 am · Permalink
I have to agree. For the guys that are worried about the longer time taken in coding, why not just do a Ctrl-H on each of the shortened variable names after you’re happy the code works, just replace the short ones with names that makes sense, and the next person that has to work on the code will be so much more productive.
· August 15th, 2008 · 10:16 am · Permalink
Completely agree. Standards are important, especially when working with a team. I like our team to code in very similar ways so that when we open another’s code it’s like looking at something we ourselves would write. This includes: var naming, denoting scope (_privateVar), organization of variables and methods, commenting properly, # of tabs, and so on.
I’m working on living documents at work right now that define our standards for our development as a whole. Agreed upon folder naming structures for deploying websites, file-naming, deploying via subversion and what-not. What you name things is important and often required (in the case of say working with a framework).
· August 15th, 2008 · 11:26 am · Permalink
I agree, its not just the case with PHP but most languages. Its so much easier to read words rather than try to decrypt some one else’s acronyms. I try to not use abbreviations but, some times find myself using shortcuts like Dir instead of Directory. 🙁
· August 15th, 2008 · 12:35 pm · Permalink
Nice article, Steph. I’ve been arguing this for years. Glad to hear there are others who can see it too. It gets even more complex with function calls etc as well when they are cryptic. One should be able to intuit a call for crying out loud, but so often I’ve seen them structured along the same lines as variables – cryptic as all get out.
· August 17th, 2008 · 12:47 pm · Permalink
Even a simple “ReqNum” is far more obvious for one of your first examples, and still retains a lot of space.
· August 17th, 2008 · 12:58 pm · Permalink
Hi Izkata,
Yes, ReqNum is much more obvious, but I’m going to say it’s still not enough. And here’s why:
1. What if you have 10 other variables, all abbr. Are you going to remember what they all mean? You’ll still have to keep looking them up. If you don’t believe me, as someone to pick for you a random chunk of open source code and do a string find/replace on all the variables within a decent method (it has to be code you’ve never seen). Easier, but it still requires more effort than it should.
2. Again, do the same, ask someone to set up some sample code for you. Now try to add some code. When you type in the variables, are you able to remember the exact characters in each or do you have to look up what the abbreviations are each time? Could it be ReqNum, ReqNb, RqNum, RequestNum, ReqNo, etc. There’s just so many rules to abbr. that you need to look it up. With fully qualified names, it’s always the full spelling 😉
· August 17th, 2008 · 1:00 pm · Permalink
And thanks everyone for the great comments!
Fully qualified names are slowly starting to become more and more the “way” to code. I can’t wait until it’s the standard!
· August 17th, 2008 · 2:15 pm · Permalink
> Fully qualified names
You know what would be great is to see some benchmarks on using longer fully qualified var-names versus short guys. I for one love fully qualified names, and IDEs with auto-complete and snippet/macros like Textmate, Zend, et al make it easy to type and re-type variables and function names so “type to write” should be less of a factor.
· August 17th, 2008 · 2:18 pm · Permalink
* speed benchmarks
* time to write
· August 17th, 2008 · 3:00 pm · Permalink
Hi Ben,
The book Code Complete 2, chapter 11 specifically (The Power of Variable Names). In it the author has some hard data (research study results) that he shares that supports the same advice as this article 😉
· July 4th, 2013 · 5:28 am · Permalink
Completely agree! Not sure when I was told to always abbreviate my variables, but since reading Clean Code I’ve stopped doing it & my code is much more readable. rqnb is horrible, at a glance it is meaningless. reqNum is what I’ve been writing for years, once you know what it’s supposed to be it is easy to convert to “request number” in your head. Using requestNumber from the get-go lets your brain skip the conversion step, reading code then flows nicer.
(assuming there are other request attributes than just the number, otherwise I’d have left Number off entirely)
· July 4th, 2013 · 6:07 am · Permalink
Also just because you know what reqNum means in your head, it doesn’t mean the next person will. This is a naming convention for you, and maybe your current project, but it’s definitely not standard worldwide 😉
Yes it might be a bit more typing to enter the full name, but it’s worth it long term.
The thing to remember is a lot of the effort in software is not in the writing itself but in the maintenance part. And it can be years later and by different people. So the difference can be very impactful.
I recently came across a really good article called “Product Strategy is Saying No” and the picture of the iceberg under the section “But It’ll Only Take a Few Minutes” really hits home in regards to this. You can find the article at: https://insideintercom.io/product-strategy-means-saying-no/