This Q&A is part of a weekly series of posts highlighting common questions encountered by technophiles and answered by users at Stack Exchange, a free, community-powered network of 90+ Q&A sites.

KChaloux Asks:

This has become a large frustration with the codebase I'm currently working in; many of our variable names are short and undescriptive. I'm the only developer left on the project, and there isn't documentation as to what most of them do, so I have to spend extra time tracking down what they represent.

For example, I was reading over some code that updates the definition of an optical surface. The variables set at the start were as follows:

double dR, dCV, dK, dDin, dDout, dRin, dRout

dR = Convert.ToDouble(_tblAsphere.Rows[0].ItemArray.GetValue(1));

dCV = convert.ToDouble(_tblAsphere.Rows[1].ItemArray.GetValue(1));

... and so on

Maybe it's just me, but it told me essentially nothing about what they represented, which made understanding the code further down difficult. All I knew was that it was a variable parsed out from a specific row from a specific table, somewhere. After some searching, I found out what they meant:

dR = radius

dCV = curvature

dK = conic constant

dDin = inner aperture

dDout = outer aperture

dRin = inner radius

dRout = outer radius

I renamed them to essentially what I have up there. It lengthens some lines, but I feel like that's a fair trade off. This kind of naming scheme is used throughout a lot of the code however. I'm not sure if it's an artifact from developers who learned by working with older systems, or if there's a deeper reason behind it. Is there a good reason to name variables this way, or am I justified in updating them to more descriptive names as I come across them?

Related: "How would you know if you've written readable and easily maintainable code?"

You're working with physicists

Justin Cave Answers (162 votes):

It appears that these variable names are based on the abbreviations you'd expect to find in a physics textbook working various optics problems. This is one of the situations where short variable names are often preferable to longer variable names. If you have physicists (or people that are accustomed to working the equations out by hand) that are accustomed to using common abbreviations like Rin, Rout, etc. the code will be much clearer with those abbreviations than it would be with longer variable names. It also makes it much easier to compare formulas from papers and textbooks with code to make sure that the code is actually doing the computations properly.

Anyone that is familiar with optics will immediately recognize something like Rin as the inner radius (in a physics paper, the in would be rendered as a subscript), Rout as the outer radius, etc. Although they would almost certainly be able to mentally translate something like innerRadius to the more familiar nomenclature, doing so would make the code less clear to that person. It would make it more difficult to spot cases where a familiar formula had been coded incorrectly and it would make it more difficult to translate equations in code to and from the equations they would find in a paper or a textbook.

If you are the only person that ever looks at this code, you never need to translate between the code and a standard optics equation, and it is unlikely that a physicist is ever going to need to look at the code in the future perhaps it does make sense to refactor because the benefit of the abbreviations no longer outweighs the cost. If this was a new development, however, it would almost certainly make sense to use the same abbreviations in the code that you would find in the literature.

How long will that variable live?

zxcdw Answers (53 votes):

Variables with short lifetimes should be named shortly. As an example, you don't write

for(int arrayCounter = 0; arrayCounter < 10; arrayCounter++) { … . Instead, you use for(int i … .

In general, it could be said that the shorter the variable scope the shorter the name should be. Loop counters are often only single letters, say i , j and k . Local variables are something like base or from and to . Global variables are then somewhat more elaborate, for example EntityTablePointer .

Perhaps a rule like this isn't being followed with the codebase you work with. It's a good reason to do some refactoring though!

Where are the comments!?

Kaz Answers (26 votes):

The problem with the code is not the short names, but rather the lack of a comment which would explain the abbreviations, or point to some helpful materials about the formulas from which the variables are derived.

The code simply assumes the problem domain familiarity.

That is fine, since problem domain familiarity is probably required to understand and maintain the code, especially in the role of someone who "owns" it, so it behooves you to acquire the familiarity rather than to go around lengthening names.

But it would be nice if the code provided some hints to serve as springboards. Even a domain expert could forget that dK is a conic constant. Adding a little "cheat sheet" in a comment block wouldn't hurt.

Find the original post here. See more Q&A like this at Programmers, a site for conceptual programming questions at Stack Exchange. And of course, feel free to ask your own.

