Style guide: When to use underscores?

[gilch]

see also #972

All we've got in the style guide so far is:

Look like a lisp, DTRT with it (e.g. dashes turn to underscores, earmuffs turn to all-caps.)

Should we also use dashes for Python's many "dunder" special names like --init-- or do we keep them as underscores like __init__? The latter is more recognizable Python, but the rule would be more consistent if it was "always use dashes". Whatever we choose, it should be stated clearly in the guide. We could also do things like -_init_- or _-init-_ or --init__ or __init--. Yeah, that looks weird, but you're forgetting that __init__ also looks weird, and then you got used to it. If any of these were standard Hy style, you'd get used to it. We could have a rule like "never mix dashes and underscores", but I don't think that's a good idea. More on that later.

The Python convention for a "private" variable is _x. At the module level it gets excluded from the from <module> import * by default. In this case I think keeping the underscore is a better choice, since -x is too easily confused with (- x). We do use a dash to mean negation in number literals like -1. So maybe "always use dashes" isn't such a good rule. What if we have a "private" compound name like _foo_bar? Should that be rendered in Hy as _foo-bar? But now we're mixing dashes and underscores. I don't think it looks that bad though.

And finally, inside a class, a double-prefixed attr like __x gets mangled to _classname__x to avoid conflicts with subclasses. Should we render this as --x in Hy? Or -_x or _-x?

We're not consistent even in the source of Hy's standard library.

[gilch]

Since no-one has commented, I'll propose what makes the most sense to me.

• Private names shall be prefixed with an underscore, not a dash.
  • _x, not -x, to avoid confusion with negated literals like -42 or -4/2.
• Python's magic dunder names shall be written the same as in Python.
  • like __init__, not --init-- or otherwise, to be consistent with the private names rule above.
• Private names should still separate words using dashes instead of underscores.
  • like _foo-bar, not _foo_bar, to be consistent with non-private parameter names and such that need the same name sans prefix, like foo-bar, not foo_bar.
• Mangled attrs shall likewise be prefixed with two underscores.
• Mangled attrs should likewise separate words using dashes instead of underscores.
  • again here it's more important to be consistent with how you would have named it sans prefix.

We could put this in the style guide, and clean up Hy's source to use this style consistently.

@algernon, is this something you could put in Hydiomatic?

[algernon]

Not sure I can do that, Hydiomatic sees the mangled names only, unless we added some meta-data to Hy while I wasn't looking (or if I was looking, I forgot). But if Hydiomatic can, somehow, figure out the original symbol name, then adding these checks would be a breeze.

[gilch]

@algernon, so you could do it if we fix #360?