I would like to propose to discuss about styling equations.
It is known that the PEP8 and other established styling documents are missing guidelines about maths. Hence everyone comes with its own interpretation and style. I believe I do not have to motivate the benefits for having a common coding style in general as this is well established (easier to share, code is familiar and coherent across the ecosystem, etc.).
I think such a document is missing from the scientific community and my hope is that we can all agree on something
To be transparent: there are heated discussions on SciPy around this topic and formatting tools. Indeed, having extensive guidelines (like PEP8) could allow such tools to implement a mathematical style. Opinion varies here around the feasibility and need of styling maths. I still think this is a good idea and has value.
To quick-start things here are some ideas. DISCLAMER: I do not claim these are correct, this is just to start the discussion. Feel free to rewrite everything. I am just proposing an idea which I believe could help the community in general. I hope we have productive chats here.
- 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))