STY: Maths formatting

This issue is linked to #14330

To be able to use tools (like, but not limited to Black), we need to define how we, as the scientific community and not just SciPy, want mathematical equations to be rendered.

The goal of this issue is to document and establish a strict set of rules to write maths. The rules must be coherent, extensive and opinionated (one way to do something, unambiguous wording) so they can be integrated in a tool (that tool may be Black).

I think such a document is missing from the scientific community and my hope is that we can all agree on something 😃

To quickstart things here are some ideas:

Formatting Mathematical Expressions

To format mathematical expressions, the following rules must be followed. These rules respect and complement the PEP8 (relevant sections includes id20and id28)

• If operators with different priorities are used, add whitespace around the operators with the lowest priority(ies).
• There is no space before and after **.
• There is no space before and after operators *,/. Only exception is if the expression consist of a single operator linking two groups.
• There a space before and after -, +. Except if : (i) the operator is used to define the sign of the number; (ii) the operator is used in a group to mark higher priority.
• When splitting an equation, new lines should start with the operator linking the previous and next logical block. Single digit, brackets on a line are forbidden. Use the available horizontal space as much as possible.

# Correct:
i = i + 1
submitted += 1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)
dfdx = sign*(-2*x + 2*y + 2)
result = 2 * x**2 + 3 * x**(2/3)
y = 4*x**2 + 2*x + 1
c_i1j = (1./n**2.
         * np.prod(0.5*(2.+abs(z_ij[i1, :])
                        + abs(z_ij) - abs(z_ij[i1, :]-z_ij)), axis=1))

# Wrong:
i=i+1
submitted +=1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)
dfdx = sign * (-2 * x + 2 * y + 2)
result = 2 * x ** 2 + 3 * x ** (2 / 3)
y = 4 * x ** 2 + 2 * x + 1
c_i1j = (1.
         / n ** 2.
         * np.prod(0.5 * (2. + abs(z_ij[i1, :])
                          + abs(z_ij) - abs(z_ij[i1, :] - z_ij)), axis=1))

[rgommers]

Let me jump in here, since apparently there’s two things being mixed:

1. do we want/need a code formatter like black?
2. is it possible to code up with consistent guidelines for writing math?

This issue is not about 1, only about 2. No change to any SciPy way of working is proposed

What black does today for math is bad, really bad. Something like hypot2 = 2 * x + 3 * y ** 2 is code no numerical Python person would write by hand. PEP 8 also falls well short here, it for example is completely silent on the power operator. So the question is: is it possible to do better than black and PEP 8. I’m pretty the answer is yes, the question is just how much better. Once we have the answer, at least there’s something to point tool authors to. Maybe black et al. can implement it, maybe not. If they did, it would be helpful.

[rkern]

the goal is to save everyone endless discussions about styling.

AFAICT, we largely do not have endless discussions about styling in the actual code reviews. We only have endless discussions about styling when someone proposes to use black.

Newcomers, students, and as you rightfully noted, people with disabilities, would greatly benefit from a common ground.

Citation needed. I have seen no evidence that the level of formatting that black and company provide any measurable benefits in this regard.

I’ve laid down this marker before, and I think it satisfies all of the evidenced benefits that you want from black: my ideal auto-formatting tool is one that leaves style-conforming code alone and only fixes up code that deviates. Somehow the benefits of some kind of auto-formatter got conflated with requiring a canonicalizing auto-formatter. black is not the only possible solution.

At minimum, a tool like darker can be fruitfully used by contributors to apply auto-formatting just to their contribution. All of the benefits with respect to the easing of writing code apply just as much to darker as to black. I recommend that you implement your preferred math styling rules in a way that can be plugged into that, and we can evaluate the results concretely rather than spinning out more endless discussions about styling in the abstract.