Improve variable naming in expressive code section

pyOpenSci / lessons

A repo containing lessons used in pyOpenSci training.

https://www.pyopensci.org/lessons

BSD 3-Clause "New" or "Revised" License

3 stars 4 forks source link

Improve variable naming in expressive code section #38

Closed willingc closed 1 month ago

willingc commented 1 month ago

This PR makes several changes:

Reorders rules to put meaningful names before short names (it's a common mistake for people to opt for brevity over clarity)
Expand precip to precipitation as it has less cognitive load and is more readable
Have directory and file names be either _ or -. Personally, I would use _ unless I was working with web/JS code and Python

sneakers-the-rat commented 1 month ago

+1 on this and it would probably be worth clarifying that python module names must use _ because names with - are not valid names

I will often use - in my package name to differentiate it from the package module name (and also that's javascript brain leaking in) but that might be too much subtlety in convention for newbies :)

lwasser commented 1 month ago

Friends - i opened #44 I do think that using verbs for function names is really important. BUT I also have observed in a complex workshop that is having a really long functions and variable names while expressive can make the code harder to read (that might be just my opinion), but I wanted to discuss it. I'm fine with merging this as is, especially given you both seem to agree that more verbose is better. I suppose for me I struggle with really long names!