Digression on short variable names

One gripe, perhaps my pet peeve: long variable names make code hard to read. It’s a wall of text with numerous very similar long names. And for a casual reader, the names carry no information. It’s just hard to follow the code.

This is why mathematics normallt use single-letter variable names.

Can you shorten the names for clarity?

3 Likes

Absolutely agree.
I’m no fan of the current ‘wisdom’ in software engineering to use long explanatory variable names.
Totally obscures the ‘gestalt’ of the code.

Explanation should go in comments and docs.

3 Likes

disagree :slight_smile:

this code is a bit exagerated, there are no spaces, no formatting… but in general I prefer much more to have a hint in the var name of what a particular variable refers to in the specific application that is under study… pure math often do not need to have an application of a particular computation, so one letter var would be fine, but I don’t think it is the case in a general way… but this is really OT to the discussion… yes, try to remove all that junk of global variables and pass them as function srguments instead…

15 Likes

[hijack]
This is where the word “concise” applies. Work hard to make the var names short and clear.

Too short names makes code inscrutable. Too long names makes code unreadable. It’s a tradeoff.
[/hijack sorry]

3 Likes

Yes I do agree; “only use single-letter variable names” is too strong. (Not that anyone said that).

But if you have sth like, e.g,

function run!(s::Simulation)
    while !completed(s)
        step!(s)
    end
    return s
end

why would you want to call the variable simulation.
sim is fine.

Indeed we’re going totally off-topic, maybe a mod could split off?

2 Likes

I totally agree. When it’s well done, complex codes with longer explanatory variable names are muuuuch easier to read than cryptic codes with math notations. Obviously this is personal preference, but I don’t want want to switch back and forth between the code and the paper/documentation to understand what’s happening. Yes, UTF-8 characters in Julia are awesome, but that’s not an excuse to clutter the code with Greek letters.

The variable is a stiffness matrix? Call it stiffness_matrix.
The variable is a list of violated constraints? Call it violated_constraints.
Reads like English.

It’s an art to figure out good names and it takes a lot of time to refine. I can only recommend Kate Gregory’s talks on the topic (e.g. “Naming is hard: let’s do better”).

Edit: why the hell would you want to call a “simulation” variable “sim”? Are we talking about a simulation or a sim card? With poor design, that’s the main reason why codes become unmaintainable. Ambiguity must be avoided.

4 Likes

I agree in a vacuum, but the whole point of short variable names is that they make sense in context. Here, the semantic context is contained within the function.
The type (sim::Simulation, i.e. disambiguation) is right there.

Take a sorting algorithm eg.
Much easier to understand with long rather than short names (see julia src).

EDIT: I meant to say “easier to understand with short rather than long names”

4 Likes

Yes, I must say it makes sense in your example because s::Simulation is never 3 lines away of the line you’re reading. But “real” functions are often longer and the frontier between “short is fine” and “short is terrible” is not that clear.
Also agree that we could fork topics :smiley:

Yes agree that the frontier is murky.

I have to note though that this is a real function (I copy-pasted it from the spiking-neural-network simulation library I’m writing, which is full of short functions).
Julia’s “structs-and-functions” design (without inheritance and mixins etc) makes short functions very common.

1 Like

Functions should be short, just like names.

And it should be stiffness, not stiffness_matrix.

5 Likes

There is a rule of thumb here:

The shorter your function, the shorter your variable names can be.

Also, in Julia (as mentioned above) argument annotations can disambiguate short variable names. But of course you shouldn’t add argument annotations just to disambiguate a variable name—only use argument annotations for dispatch. :slight_smile:

The other dimension here is library vs application code, with the rule of thumb being that application code requires longer variable names than library code.

3 Likes

:tada::tada::tada::tada::tada::tada::tada:

2 Likes

I loved this one.

As a rule to myself, I always try to make functions not taller than a laptop screen height. Then I feel free to use very short-up-to-one-single-char variable names because I can read all function without up-down scrolling. When that is not possible, I try that in the day after I still can tell what a variable name stands for just by reading its name.

4 Likes

I for one am so happy to have, for example, λ rather than lambda as a variable for eigenvalues, instead yhat for a discrete approximation of y in an ODE integration, etc.

I really appreciate this in teaching, since it relieves students of the burden of learning to recognize both the chalkboard math and ASCII code conventions for the same quantity.

13 Likes

What a nightmare it would be if we replaced x with unknown in mathematical formulas or in code.

5 Likes

I agree with that; though there is a tradeoff of course, even calling it lambda requires that the reader of the code knows that that refers to Eigenvalues.
On the other hand the code is super-easy to read for all of us who know this convention in naming – and maybe if one reads the code and has to know about eigenvalues anyways – lambda is fine. And then of course also the UTF-8 – I also love to use those then, since it is so much more readable.

On the other hand, one maybe should not “invent” such short variables for own things too often unless clear from context line in the above sim::Simulation within nice short function.

4 Likes

\theta for potential temperature is fine
\ell for something down one page, is not. It looks pedantic to me.

3 Likes

Good point. In the end, I think the bottom line is: if you’re the only reader of the code, do whatever pleases you (and maybe regret it 3 months later). If not, work hard on the names.

2 Likes

Nice summary – maybe extended by: Know your (code-reading) audience :wink: If you are in a math/physics/… area where everyone knows some fixed variable convention – it makes code really beautiful to read (for the knowledgable wizard).

1 Like

This is what the let statement is for, both in programming and in mathematical proofs: so that variables can have verbose descriptive identifiers in larger/global contexts, but short concise names within local contexts where we’ve specified what we’re talking about and our interest shifts toward manipulating the symbols.

And when that doesn’t cut it, we have module encapsulation too.

3 Likes