carpentries-incubator / carpentries-incubator/python-intermediate-development
Episodes 3.2 & 3.3: Swap ordering?
- Dominant language
- TeX
- Stars
- 63
- Forks
- 77
- Avg merge
- 20h 8m
- Merged PRs (30d)
- 3
Description
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.
Contributor guide
Assessment
This issue has not been assessed yet.