PEP 8 lesson - reorg ideas from Jonny :heart: & carol 🫶

[lwasser]

          OK Leah, love it, and i hadn't seen the rest of this so i got carried away reading around the rest and i love that too. I think my role in reviewing your writing is always just "take all the really good stuff here and suggest totally switching the order around," which is hopefully clear at this point that you can always take or leave, totally up to you. I have been going through this recently with some new labbies who are just getting booted into collaborative coding for the first time so this is very top of mind for me and wished i had a resource like this!

One thing i'm missing here is an overview of "what are the kinds of things that might be subject to style rules." The examples are good, but some bigger picture categories that i could group things into: naming, comments, whitespace, character use (tabs/spaces, '/"), syntax (eg. using a ternary rather than if/else, etc.). I think reordering that section, adding subheadings between each of them, would make it easier to digest :)

Current structure:

- Why code style and Python PEP 8 matters
- How to Apply PEP 8 Code Style Standards
  - For .py Files
  - For Jupyter Notebooks
  - Running These Tools
- Why use code standards when writing Python code
  - Some PEP 8 rules to remember
- PEP 8 naming conventions
- Best practices for importing libraries
  - Import Python libraries at the top of your code
  - Organize your imports into groups
  - Why organize imports?  

So this is how i would do it (but as always not saying you have to):

- What is code style
  - introductory example (the formatted/unformatted sentence & code examples) 
  - why does it matter for code (code is read more than it's written, merges, etc. all the reasons)
- Common python conventions
  - Formatting (big, top-level, "how is the document structured")
    - Whitespace
    - Imports & Order  
  - Naming (medium, single objects)
    - Capitalization
    - Special characters like l/l
  - Annotations (Notes to self!)
    - Comments
    - Docstrings  
- Tooling
  - what are linters & formatters?
  - examples
    - .py files
    - notebooks
  - pre-commit (why you would do it and links to other guides on how to do it)
  - IDE integration (links to examples)

One other sorta tangential thing- think it's important to give the other side so this too, that they shouldn't feel restricted by linters/formatters! they should use them if they support their work and help them think clearly. If they find a rule annoying? they should turn it off. it's their call. i don't mean to be annoying or overly ideological about this since i am known to make a big deal about standardization in devops but figured i'd bring it up.

Originally posted by @sneakers-the-rat in https://github.com/pyOpenSci/lessons/pull/12#pullrequestreview-2363727185

[lwasser]

@sneakers-the-rat i welcome edits to this lesson to reorg it some if you want to implement them! otherwise, i'll do it after the fall festival 🚀

I haven't documented the setup here, but it's a sphinx book running pydata_sphinx_theme by myst_nb and jupytext. So, using Jupy, I only commit the .md files, making for lovely, easy diffs! Locally you have to set this all up, and I haven't had time to document it - YET, but I'll do my best to make that happen soon!!

[lwasser]

Ok - and here is the feedback on org from @willingc @lwasser @sneakers-the-rat Let's split this PR up or merge as is and then do another iteration. I'm finding it difficult to work with all three files in the same PR and follow proposed edits.

I would love to see something more along the lines:

• Create maintainable code
  • Why it's helpful
  • What are elements of maintainable code
    • Clean
    • Modular
    • Readable
    • Consistent code style
    • DRY: minimize code repetition
• Code style
  • What is code style
  • Why it's important
    • Easier to maintain
    • Easier to change and review
  • Types of tools (generic)
    • Linters
    • Formatters
    • Integrated into editors, IDEs, CI
• Python code style: PEP8 and beyond
  • PEP8
  • black

Etc.

link here: to the formatted comment

we will need to come together on a structure that makes sense for this section!

[sneakers-the-rat]

I think the only major difference between Carol and my suggestions are the order of "overview, tooling, rules" vs. "Overview, rules, tooling" and I would be fine with either.

I actually slightly prefer Carol's version, because then we could tag each of the rule suggestion sections to a ruff/pyflakes/etc rule code.

The difference between current version and reorganized version would then mostly be to group related content and provide a little more structure for skimming, which doesn't seem too complicated :)