Document policy on use of non-ASCII characters

Last year, @Meuge used the original Greek names in her contributions to the poliastro.earth package, and I was ambivalent about it but I agreed to go forward. But then @Yash-10 opened #1191, in which he initially brought the variable names back to ASCII-only.

This is something that has been irking me for some time, and I would like to read other opinions. I think there are basically 3 options:

• Short, ASCII-only names: for example (a, ecc, inc, raan, argp, nu). This is what we currently use almost everywhere.
  • Pros: Short, easily identifiable names. Easy to type in any keyboard.
  • Cons: Sometimes we need transliteration of Greek letters (nu instead of ν) or we do a visual (wrong) transliteration (n instead of η). Also, they rely on a specific convention (nu instead of theta), and we are often inconsistent (nu instead of ta for “true anomaly”, a instead of sma for “semi-major axis”).
• Long, ASCII-only names: for example (semi_major_axis, eccentricity, inclination, right_ascension_ascending_node, argument_periapsis, true_anomaly).
  • Pros: Easier to identify, no need to rely on a specific symbol convention.
  • Cons: They are way too long 😭
• Short, non-ASCII names: (a, e, i, Ω, ω, ν)
  • Pros: Short, easily identifiable names. Code looks similar to mathematical formulas. Julia people stop bragging that they’re the only ones who can do it 😜
  • Cons: Difficult to type in a normal keyboard, difficult to search, relies on a specific naming convention.

And some considerations:

• If there is no consensus, the status quo wins. Meaning: current variable naming convention, current symbols convention, some inconsistency here and there.
• There are backwards compatibility concerns at play. Sure, poliastro is still 0.x, which means “we can break everything at any time” (and we do, all the time). However, changing (a, ecc, inc, raan, argp, nu) is a major change that should be justified.
• And finally, for once I would like to take an evidence-based approach. So: yes, I want to hear everyone’s opinions on this. But if you back your opinions with data, your opinion counts more 🙃

[helgee]

Some perspective and lessons learned from the Julia side since we have been doing this for a long time 😉 😉 😉

• If you are transcribing equations from a textbook or paper, using Unicode identifiers is great and easily recommended. In my opinion χ₁ = √μ * Δt * α beats chi_1 = sqrt(mu) * delta_t * alpha by a mile in terms of readability.
• While the Julia community has a nifty workaround for the input struggle, both the REPL and all editor plugins for Julia support a subset of LaTeX, e.g. you can type α as \alpha<TAB>, you are still hosed when you use e.g. plain Vi or Nano.
• The general consensus in the community seems to be that you can go crazy with Unicode inside your functions but the public API of packages should remain ASCII-only. I would also always recommend long_snake_case over lsc so that the short names remain available for scripting. So stumpff_c2 instead of c₂ or c2. I guess the latter point is not that important in Python because the convention is to qualify all imports.
• I do not have data for whole Julia ecosystem (although that would be an interesting analysis) but all the astro* packages that I use and are involved in use Unicode identifiers and there have been no complaints so far.

Finally here is a satirical package that serves as a cautionary tale about what happens if you do not show restraint about Unicode: https://github.com/theogf/WatchJuliaBurn.jl

[astrojuanlu]

In other words: this is now a documentation issue 😃