feat(lesson): pep8, linters & code formatters

[lwasser]

todo: add to bottom of intro clean code page:

[^zenofpython]: Paste this into your shell: python -c 'import this'``

[sneakers-the-rat]

"that are included with python," "that you don't have to install," with link to https://docs.python.org/3/library/index.html ?

[sneakers-the-rat]

maybe add the third block of

# imports from your local package
import mypackage
from mypackage.internal import _secret_function

?

[sneakers-the-rat]

oh i see you have a separate section for that. my b. i just figured showing all three of them in the example that follows the list of 3 would be nice, but this is a draft and i'm jumping the gun on giving comments lol

[lwasser]

go for it!! comment away. i just combined two pages. i'm totally fine with consolidating!!

This is good, too, because in our second workshop, they will create a package and import it. so they will get to try this out!!

[lwasser]

I've just pushed a new version of this and made all of the fixes that you suggested. I also redesigned the structure to be:

• Example of good vs not as good code format.
• How to apply tools to help you make your code prettier :)
• Why use these tools and standards
• Some rules to remember

That way, we start with something that doesn't have to be so hard and end with the details that many people will skip (I think?).

[sneakers-the-rat]

I hear you on that but i think that currently it's a little bewildering the other way where we're missing some introductory information on what we're talking about and why first, about to post the review

edit: oh wait it makes this comment part of the review even when we started it before that lol my b

[lwasser]

😆 no worries!! i think / hope that i addressed your comment!! I am going to focus on merging this today give we are a week out BUT we can always revisit all of this content and update/ enhance / beautify, etc in the future!! 🚀

thank you for this feedback!!

[willingc]

Nice!

[willingc]

Let's alphabetize these imports.

[sneakers-the-rat]

isort makes it a little hard to know what the rules are exactly but if we want to add the sorting rules in here, here are the most common rules (in addition to grouping and alphabetization):

• modules:
  • module-only imports (import x) come before imports with objects (from x import y)
  • within that, import statements sorted alphabetically by module name
• objects within a module import (the y in from x import y)
  • first sort by whether the first letter is capitalized or not
  • then alphabetically

[sneakers-the-rat]

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.

[sneakers-the-rat]

Suggested change

	"Pythonic" code is code that follows the conventions and best practices of the Python programming language. It emphasizes code that is clear, concise, and readable--principles that adhere to Python's design philosophy.
	"Pythonic" code is code that follows the conventions and best practices of the Python programming language. It emphasizes code that is clear, concise, and readable--principles that adhere to Python's design philosophy.[^zenofpython]

and at the bottom

[^zenofpython]: Paste this into your shell: `python -c 'import this'`

[sneakers-the-rat]

probably should have pep-8 in the title if it's going to be in the url.
"Python style conventions, PEP-8 and friends" something like that. or else change the name of the file to be code-style

[sneakers-the-rat]

I think it might be easier for newbies to keep some of the old way of introducing this, "what is code style" and then "what is PEP 8" in sequence. So "what is code style and why should I care," and then "PEP-8 is one/the main/the most common set of python code style guidelines." We're dropping in a little hard here where I am not sure what PEP-8 is at the same time i'm trying to hear what you're saying about why style is important

[sneakers-the-rat]

Also, I think it's worth expanding this a bit before getting into the examples - some other things i think are worth covering from the top:

• that pep8 is just one example, that there are a ton of style guides and sub-rules and preferences. There isn't "one right python," but there are some generally agreed upon styles that one would consider idiomatic (or pythonic) python as well as a lot of gray area around the edges. we're going to talk about pep-8 in this lesson because it's the most common. hint at this at the top and then we can give some more examples at the bottom for further reading
• the other major reason to use (and enforce) a code style is that is makes collaboration on large projects a lot less of a pain in the ass. rather than having to wade through 500 lines where someone nudged some whitespace, or getting merge conflicts from the absence of a trailing comma, there is one unambiguous way that the code should be (modulo all the stylistic space that the style guide doesn't regulate)
• Linters also make code easier to write - i often find myself just writing sludgy garbage and then saving and letting the linter figure it out for me. Code style makes it so you don't have to think about the formatting as you write.
• Another is that consistent style makes bugs in code easier to recognize. If you're not bogged down by having to constantly adjust to the 50 different ways that the same pattern is written, you can see what the code is doing more clearly. bugs can "look wrong" when you have a clear expectation of what the code "should" look like.
• It also gives external contributors a clear target to aim for. Rather than someone having to manually review and say 'in this project we do this not that,' or outright rejecting a PR because it's ugly (to the maintainer), clear code style guidelines give an unambiguous thumbs up/thumbs down on whether a contribution is adherent to the style.
• I think it would also be good to add a footnote or a breakout box or something like "don't worry about your code being perfect. the goal of linting tools is to reduce stress not add to it - there are still many "correct" ways to write things, and your code is not bad if it is not adherent to the styles"

[sneakers-the-rat]

the single space is killing me

[sneakers-the-rat]

this is odd to me to have as its own top-level section after listing a bunch of pep 8 rules in the previous subsection, and it seems to be the same information as the example starting on line 179? i would combine those things and put them under a section on various types of conventions. i'll give an example ToC in the main comment

[sneakers-the-rat]

section starts "first" but there is no next!

[sneakers-the-rat]

I hear you on that but i think that currently it's a little bewildering the other way where we're missing some introductory information on what we're talking about and why first, about to post the review

edit: oh wait it makes this comment part of the review even when we started it before that lol my b

[sneakers-the-rat]

isort makes it a little hard to know what the rules are exactly but if we want to add the sorting rules in here, here are the most common rules (in addition to grouping and alphabetization):

• modules:
  • module-only imports (import x) come before imports with objects (from x import y)
  • within that, import statements sorted alphabetically by module name
• objects within a module import (the y in from x import y)
  • first sort by whether the first letter is capitalized or not
  • then alphabetically

[sneakers-the-rat]

and merge conflicts, but i think basically we should consolidate "why code style" at the beginning because it's mostly the same reasons

[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.

[willingc]

@lwasser Let's merge this as is and iterate on separate PRs.

[lwasser]

Ok fantastic yall. Let's do this

1. When I'm back at.my computer I'll turn the bigger comments into issues!
2. I already committed the online edits!
3. I'll merge so we can then iterate on smaller prs. This likely will happen after the fall festival but I'm excited to work on this with everyone!! And I'll keep each pr small from here on in..

I hope that works for you both!! ✨️