deploy: d820c23

_sources/encapsulation.md.txt

@@ -0,0 +1,23 @@
+# Types of encapsulation
+
+Let's say you want to move a code from one system to another.  What are the things that can go wrong?
+
+- **In-language dependencies**, e.g. Python. Can they all be expressed *only* in
+  ``requirements.txt``?  Do you wrap everything in a container?
+- **Paths**: Can you always use relative paths?
+- **Operating-system (OS) dependencies, libraries, etc.**: Can you eliminate them?
+- **Data files**: Are they controlled or few that you can migrate, or if you wanted
+  to move it, are you forced to copy the whole directory without regard to what
+  the file is (thus creating a lot of duplicates, and a big mess?)
+- Are you using something that is **OS-specific** (GNU/Linux vs BSD)?
+- Do you use support programs only available on certain computers?  Fewer
+  external utilities you use = easier portability.
+
+
+## What needs to be global vs what needs to be local?
+
+- Global data can be "seen"/accessed in the entire code.
+- Local data is only available in the local vicinity of its definition.
+- Try to have as little global data as possible.
+- Global data are often input parameters, configuration parameters, command-line arguments.
+- But try to localize these to the "main" code/function.

_sources/index.rst.txt

@@ -0,0 +1,45 @@
+Modular code development - Making reusing parts of your code easier
+===================================================================
+
+Type-along/demo where we discuss and experience aspects of (un)modular
+code development. **We will focus on the "why", not on the "how"**.
+
+Image to get started: `The curse of bad code design <https://doi.org/10.1371/journal.pcbi.1008549.g005>`_
+(Ten simple rules for quick and dirty scientific programming. PLoS Comput Biol 17(3): e1008549. https://doi.org/10.1371/journal.pcbi.1008549)
+
+
+Slides
+------
+
+We also have some slides:
+https://github.com/coderefinery/modular-code-development.  But here we will try
+to do this as collaborative type-along where instructors try to solve a problem
+together and where learners guide the instructors through a collaborative
+document.
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: The lesson
+
+   questions
+   learning-outcomes
+   lesson
+   encapsulation
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Solution
+
+   solution
+
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: About
+
+   All lessons <https://coderefinery.org/lessons/core/>
+   CodeRefinery <https://coderefinery.org/>
+   Reusing <https://coderefinery.org/lessons/reusing/>

_sources/learning-outcomes.md.txt

@@ -0,0 +1,18 @@
+# Learning outcomes
+
+- Know about **pure functions** (functions without side effects, functions which
+  given same input always return same output).
+- Learn why and how to **limit side effects** of functions.
+- Discuss why and how to limit side effects of data. Also discuss when
+  mutable data may be preferable.
+- [The Zen of Python](https://www.python.org/dev/peps/pep-0020/)
+- Discuss why **single-purpose functions** are often preferred over
+  multi-purpose functions.
+- **Split-apply-combine**, which lets you more easily parallelize. Make your code
+  modular in a way that lets you split the steps and parallelize.
+- Think about **global vs local** data structures. It is not easy to
+  separate them right.
+- Understand how a command line interface to a code can improve usability and also
+  make the code more versatile (to be combined with workflow management tools).
+- Connect modular code development to the remaining lessons (version control, testing,
+  documentation, reusability).

_sources/lesson.md.txt

@@ -0,0 +1,67 @@
+# Our task
+
+
+## Data
+
+The file [temperatures.csv](https://github.com/coderefinery/modular-type-along/blob/main/data/temperatures.csv)
+contains hourly air temperature measurements for the observation station
+"Vantaa Helsinki-Vantaan lentoasema" (Helsinki airport) during 2022.
+
+```{admonition} Origin of the data
+Data obtained from
+<https://en.ilmatieteenlaitos.fi/download-observations#!/> on 2023-09-27.
+
+Data has been provided by the Finnish Meteorological Institute
+under the Creative Commons Attribution 4.0 International license (CC BY 4.0):
+<https://en.ilmatieteenlaitos.fi/open-data-licence>
+```
+
+
+## Our initial goal
+
+Our initial goal for this exercise is to plot a series of temperatures
+for **25 measurements** and to compute and plot the **arithmetic mean**. We
+imagine that we assemble a working script from various StackOverflow/ChatGPT
+recommendations and arrive at:
+
+```{literalinclude} code/initial-version.py
+:language: python
+```
+
+This example is in Python but we will try to see "through" the code and
+focus on the bigger picture and hopefully manage to imagine other
+languages in its place. For the Python experts: we will not see the most
+elegant Python.
+
+
+## Further goals
+
+- Once we get this working for **25 measurements**, our task changes to also
+  plot the **first 100** and the **first 500 measurements** in two additional
+  plots.
+- Then we wish to generalize the code so that a user can compute and plot this
+  for **any number**, **without changing the code** (with a command line interface).
+
+
+## How we plan to solve it
+
+Before we attempt to do this, we discuss with workshop participants how
+they would tackle this problem.
+
+Together we improve the code based on suggestions from learners towards
+more modularity and re-usability.
+
+```{instructor-note}
+Participants give suggestions and ask questions via collaborative document
+and instructor(s) try to follow and answer. They can also roughly follow
+the ideas and steps in the {ref}`guide`.
+
+It is OK and good if mistakes happen and it is fun if the instructor(s) can
+convey a bit of "improv" feel to this lesson.
+```
+
+
+## Additional exercises
+
+Draw a call tree for one of your recent projects. Identify the
+functions in your call tree which are "pure" (which have no side-effects).

_sources/questions.md.txt

@@ -0,0 +1,24 @@
+# Starting questions for the collaborative document
+
+We share these questions in a common collaborative document and we
+wait until we have sufficiently many answers to question A. But we also
+encourage answering other questions which we revisit at the end of the
+demo.
+
+```
+A. What does "modular code development" mean for you?
+B. What best practices can you recommend to arrive at well structured,
+   modular code in your favourite programming language?
+C. What do you know now about programming that you wish somebody told you earlier?
+```
+
+
+## Additional questions
+
+```
+D. Do you design a new code project on paper before coding? Discuss pros
+   and cons.
+E. Do you build your code top-down (starting from the big picture) or bottom-up
+   (starting from components)? Discuss pros and cons.
+F. Would you prefer your code to be 2x slower if it was easier to read and understand?
+```