Best practices for scientific variable naming?

Question

What are some of the conventions you use when naming variables in mathematical/scientific code? I'm looking to establish a set of conventions for an upcoming project. So here's an example formula to compute instantaneous velocity:

u'_i+1 = u'_i + 0.5dt_i (u''_i + u''_i+1)

Some possibilities include:

def up_next(up_current, upp_next, upp_current, dt):
    return up_current + 0.5 * dt * (upp_next + upp_current)

Or maybe:

def velocity_next(velocity_current, acceleration_next, acceleration_current, interval):
    #...

Are there any best practices in this regard, or is it entirely subjective? Has there been any convention which you've found to be particularly readable?

Answer 1

In mathematics, the convention is to use single-letter variables that are possibly disambiguated by subscripts or marks like primes or carets. This makes sense since adjacent symbols ab are understood as multiplication a·b, not as a single variable.

In most programming languages, this is not the case – some languages even ignore spaces in variable names – and variable names are encouraged to consist of full words. Also, most programming languages do not have a notation for typographic subscripts etc. but are are rather one-dimensional. It is therefore not advisable to do a direct translation from formulae to source code. However, your intention likely is to allow a reader of your code to immediately understand the connection to the mathematical concepts written elsewhere. This requires some amount of similarity in your variable naming.

Some languages do support Unicode letters in variable names, or even arbitrary names through stropping. I've found that this makes code more readable when you are comparing the code with the mathematical formulae, but without a convenient TeX-style system to enter these characters (in contrast to numeric escapes), such code is far more difficult to write. Needing a character table from which to copy–paste variables is not acceptable. I would consider expending this effort for code being published in a scientific context, but not for code that would be actually used (and modified, and refactored).

I have therefore come to the conclusion that a compromise seems optimal. Single-letter variables are acceptable, but non-Ascii characters are generally spelled out with a familiar name. I might indicate a subscript with an underscore in the name, and a prime by appending an underscore. This obviously fails if we have a prime and a subscript as in your case, so it makes sense to converge the mathematical notation and the code to a notation that can be easily mapped to each other by a reader.

In your case, the primes are used to mark derivatives, and the subscripts to index elements in the list being built. Depending on what you're trying to express, those indices could be actual array indices. The primes are annoying here, so you could use a different notation. x' (Lagrange's notation) might also be understood as

• ẋ (Newton's notation), especially applicable if you've derived for t, could be rendered as xdot, or x_dot, or dot_x, with the second derivative dotdot_x, which is similar to the way the mathematical symbol would be pronounced. This would be my preference.
• dx/dt or (d/dt)x (Leibniz's notation), could be rendered dx_dt, or x_ddt, with the second derivative x_d2dt2. To be honest, this would get cumbersome unless the code is about differentiation itself rather than application of differentiation to a problem.

Rendering primes as p as in up makes me think of a direction, not of derivatives.

Outside a scientific context, this is not acceptable, and the normal language-specific best practices should be preferred. Instead of cryptic symbols that are not obvious without external knowledge, variable names should convey the meaning of the variable in a self-documenting manner. Your second naming example seems to be a good approach then.