carpentries-incubator / carpentries-incubator/python-intermediate-development
Episode 1.5: Include fewer rules, more illustrative examples
- Lingua principale
- TeX
- Stelle
- 63
- Fork
- 77
- Merge medio
- 20h 8m
- PR unite (30g)
- 3
Descrizione
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).
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia con il materiale di Episode 1.5 e confrontane la copertura con quella dell’episodio IDE precedente, dell’episodio successivo sui linters e del materiale collegato Managing an Academic Software project. Rielabora l’episodio attorno a esempi che dimostrino come lo stile favorisca la comprensione, decidendo al contempo come presentare Sphinx, ReadTheDocs ed eventualmente Yardang; il lavoro è completato quando la lezione non si limita più principalmente a elencare regole imposte dal formatter e insegna chiaramente il valore di uno stile leggibile.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- python
- Ambito
- documentation
- Tipo di issue
- Documentazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Stato di attività
- Ferma
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 35/100