carpentries-incubator / carpentries-incubator/python-intermediate-development
Episodes 3.2 & 3.3: Swap ordering?
- Lingua principale
- TeX
- Stelle
- 63
- Fork
- 77
- Merge medio
- 20h 8m
- PR unite (30g)
- 3
Descrizione
Episode 3.2 feels a bit abstract and doesn't sufficiently prepare learners for the tasks they're asked to do - for example, it asks them to draw a workflow diagram for a new architecture without actually showing them any examples of workflow diagrams.
It then launches into a description of MVC interfaces, but without much context for them or illustration of why they're useful & important. If anything, the description that MVC is designed for systems with user feedback loops suggests it's irrelevant for people whose experience with scientific programming is mostly "Run simulation -> write data to CSV -> plot" or "Get data from CSV -> analyse -> plot" (which is I expect most of the audience).
We _then_ introduce Object-Orientation, but only fairly superficially, and don't illustrate existing OO systems, or provide _examples_ of the benefits they offer (just text descriptions), before asking learners to do an OO refactor.
I think it would communicate how to architect a bit better if it was structured like:
1. Objects are described, with code examples of how they help in e.g. pipelines (reference SciPy e.t.c.).
2. We do an example data flow diagram, then ask them to make a workflow diagram for this code (e.g. mentioning Yourdon diagrams)
5. We look at the DFD we made and point out which bits of data & functionality could be encapsulated, then talk about interfaces.
6. We ask them to make a class diagram for this code and describe the interfaces.
7. We get them to refactor the code to class-based, using those interfaces.
8. We introduce polymorphism, and get them to rejig it to an abstract base class + implementations.
9. We introduce the ideas of cohesion and coupling, and discuss the benefits gained from them.
10. _Then_ we introduce MVC as the way this project is structured, as a low-coupling design, and mention there are a range of other designs.
In general, IMO these sections would benefit from more diagrams and code/pseudocode, and a reduction in text. Using a 3-level example structure would help:
* **More abstract:** E.g. animal/cat/dog.
* **Generic scientific:** E.g. loading data, analysing it, and saving the output.
* **Concrete scientific:** The actual example code.
Introducing abstract concepts, then showing what that means in a scientific context, _then_ asking people to do it themselves.
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Leggi gli Episodes 3.2 e 3.3 attuali e confronta la loro sequenza con la progressione proposta in questa issue. Identifica dove dovrebbero essere aggiunti o riordinati diagrammi, codice o pseudocodice ed esempi astratti, generici e concreti. Il lavoro è completato quando le lezioni introducono i concetti e gli esempi prima di chiedere agli studenti di applicarli.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- python
- Ambito
- content, 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