Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve variable naming in expressive code section #38

Merged
merged 2 commits into from
Oct 22, 2024

Conversation

willingc
Copy link
Contributor

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

@willingc willingc requested a review from lwasser October 21, 2024 20:47
@sneakers-the-rat
Copy link
Contributor

+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
Copy link
Member

lwasser commented Oct 22, 2024

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!

@@ -131,21 +134,19 @@ in a numeric format in degrees Fahrenheit to Kelvin.

```python

def fahr_to_kelvin(fahr):
def convert_fahrenheit_to_kelvin(temperature_fahr):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sneakers-the-rat @willingc so here what i LOVE and like to suggest is

  • use a verb for function names

What i love less is -- if we write everything out now you have

convert_fahrenheit_to_kelvin(temperature_fahrenheit)

and as you add more of these and typing and such the line lengths get really long. At some point the code becomes longer and more to read. so i'm really torn about some of these suggestions but also open to merging and discussing separately!

@lwasser lwasser merged commit 6c36683 into pyOpenSci:main Oct 22, 2024
4 checks passed
@willingc willingc deleted the expressive-code branch October 22, 2024 00:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants