Add advanced lesson on naming [was: Do we want super long variable names in our lessons?]

[lwasser]

I like how expressive these names are. My only concern is they are so long! for the lessons we could do this but in my code I find really long names to make it harder to read too. @willingc do you have any thoughts on this? i love the use of a verb for the function convert_fahr_to_kelv might be a bit shorter

Originally posted by @lwasser in #37 (comment)

[willingc]

In the era of tab-completion, I find the "too long" variable to be less relevant. As a reviewer (or maintainer or future me), I find descriptive variables far easier to understand. For example convert_fahr_to_kelv is less clear to me six months from now than convert_fahrenheit_to_kelvin. When I read the first as a reviewer, I need to do a cognitive shift each time that I see the abbreviation. I suppose if you want a shorter version, convert_to_kelvin would be reasonable.

Great names are one of the best ways to reduce errors in code.

[willingc]

In general, I avoid abbreviations.

I suppose in the real world, I might write it more generically: convert(temperature, from=F, to=K)

[sneakers-the-rat]

fwiw i would name that "fahrenheit_to_kelvin" because "convert" is implied by the "to" construction.

in practice what I would do is

class Fahrenheit(float):
    def to_kelvin(self) -> "Kelvin": ...

class Kelvin(float): ...

# and i would also probably alias a shorthand like
F = Fahrenheit

but that's not great for intro lessons probably.

edit: I find myself in naming conversations with other programmers like... extremely frequently. I'm not sure if we want to flag this once in lessons like "lots of people have lots of opinions about names, so there isn't one right way to do this, but just go with our names for now" so we can address it in a single spot and then not worry too much about it

edit2: as far as what might be useful for a lesson, I think "use your context" is a super important and subtle lesson. So eg. I find myself needing to remind my lab members that in their project "miniscope_firmware" they don't need to name things like "miniscope_firmware/miniscope_init/miniscope_init_c/miniscope_init.c" because the miniscope part is implied by all the outer scope. So it might be nice to do something like "if you find you need to make all your function names super long to make it clear what they do, that might be a sign you need to refactor your code." where you might want to eg. have a module structure like temperature.conversion.fahrenheit_to_kelvin/temperature.conversion.f_to_k where the containing packages tell us more about what the individual function does, and make abbreviations like "f_to_k" acceptable because in the context of "temperature conversions," "f" and "k" have unambiguous meaning.

I think that fits into the lesson theme of "expressive code" as a reminder that expression happens in multiple forms, naming is a big one, but package structure is also an expressive system (and a really important one!)

edit3: actually i'm gonna split that off into a separate issue :)

[willingc]

I've changed the title of this issue to reflect that someday the suggestions here could make their way into an advanced naming lesson.