Notation guidance on documentation Style Guide

[martinacantaro]

Add guidance on notation to the Jupyter Notebook Style Guide, so that the style is consistent throughout the documentation.

@OriolAbril 's suggestion:

if we use $\theta$ in a math equation, should we use theta or θ? Or (probably my favourite) try to stay away from greek/one word letter variables and use meaningful names in both math and code?

[fonnesbeck]

Using meaningful names is a good rule of thumb, but sometimes it makes sense to use Greek as a shorthand, and makes equations easier to read. I vote for LaTeX over Unicode, as it is more flexible.

[OriolAbril]

This may be very nitpicky, but if the equation uses greek letters with latex like:

should the code use alpha, sigma_alpha, beta... or α, σ_α β...

[martinacantaro]

I'm not sure about the last question. But I incorporated the other comments to the style guide here https://github.com/pymc-devs/pymc3/wiki/PyMC3-Jupyter-Notebook-Style-Guide

[ricardoV94]

Regardless of what is used in the equations, PyMC3 code should use the spelled letters alpha, sigma. Using variable names with unicode symbols is cute but a PITA if you want to change the code.

We can also have meaningful names, but then the equations should use the same (both can be abbreviated to prevent cumbersome long names ofc).

I am not against having some examples use meaningful names and others use Greek letters. I think this can depend on how abstract or applied the example is.

[martinacantaro]

Added the rule about no unicode variable names inside the code to the guidelines. Right now, variable naming guidelines look like this:

Variable names

• Above all, stay consistent with variable names within the notebook.

• Use meaningful variable names wherever possible. Our users come from different backgrounds and not everyone is familiar with the same naming conventions.

• Sometimes it makes sense to use Greek letters to refer to variables, for example when writing equations, as this makes them easier to read. In that case, use LaTeX to insert the Greek letter like this $\theta$ instead of using Unicode like θ

• If you need to use Greek letter variable names inside the code, please spell them out instead of using unicode. For example, theta, not θ.

[OriolAbril]

Updated to

---

Variable names

• Above all, stay consistent with variable names within the notebook. Notebooks using multiple names for the same variable will not be merged.

• Use meaningful variable names wherever possible. Our users come from different backgrounds and not everyone is familiar with the same naming conventions.

• Sometimes it makes sense to use Greek letters to refer to variables, for example when writing equations, as this makes them easier to read. In that case, use LaTeX to insert the Greek letter like this $\theta$ instead of using Unicode like θ.

• If you need to use Greek letter variable names inside the code, please spell them out instead of using unicode. For example, theta, not θ.

• When using non meaningful names such as single letters, add bullet points with a 1-2 sentence description of each variable below the equation where they are first introduced.

---

so I'll close this issue