carpentries-incubator / carpentries-incubator/python-intermediate-development
Episode 1.5: Include fewer rules, more illustrative examples
- Dominant language
- TeX
- Stars
- 63
- Forks
- 77
- Avg merge
- 20h 8m
- Merged PRs (30d)
- 3
Description
This episode covers code style and lists a lot of the PEP8 requirements. A good chunk of it is basically just listing the PEP8 requirements, without necessarily explaining what a given style choice contributes to readability. There's plenty of examples, but most of them are effectively equally readable, and don't necessarily illustrate the _point_ of code style.
Given the previous episode is on IDEs and the next is on linters, listing lots of rules is a bit superfluous - people will automatically pick them up from the linters. Users never even need to _implement_ those style features, as since the material was first developed code formatters have become standard in Python development, and so much of the episode is on things that users don't (or at least **shouldn't**) really have a _choice_ over.
(In the spirit of #491 I'd advocate for changing **1.6** to use `ruff` and end with setting up a pre-commit hooks to auto-fix the code)
I think this episode would benefit from re-focusing on examples that show the _value_ of code style in aiding comprehension, with examples showing how poor style makes code less clear. I have a bit sort of relevant in the [Managing an Academic Software project material](https://southampton-rsg-training.github.io/project-novice/project-novice-writing-sustainable-code). There's an argument that e.g. "how to name functions and variables" is not a formal standard in the way that PEP8 is, but I think the fact whitespace style is a consensus is *why* we don't need to focus on it.
It would also be helpful if we emphasised the value of Sphinx in the section on comments & docstrings (it's briefly touched on) - we can then make a bigger point of ReadTheDocs, or (if we're following #491 and switching to pyproject.toml from the start) have a bit on adding [Yardang](https://yardang.python-templates.dev/docs/src/overview.html).
Contributor guide
Assessment
This issue has not been assessed yet.