Refactor "Structuring Code" episode

[cc-a]

Personally I've always found this episode a little tricky. Whilst I feel like the core concepts are strong I'm not sure some of the examples are that clear or compelling. One thing that I think has always worked well is the recipe exercise however.

What do people think about refactoring this section to use the recipe as the primary example? At the moment the recipe text is total chaos so I'd probably rewrite it into a more semi-structured form bearing in mind that we'll pull out particular bits to highlight the various conceptual tools.

Thoughts @ImperialCollegeLondon/rse-team ?

[AdrianDAlessandro]

Do you mean replacing the current scientific paper analogy with the recipe one?

[cc-a]

Basically... yeah.

[dalonsoa]

It makes sense. A recipe is way more familiar to most people and easier to understand. It also aligns the examples and exercises in this course with those of the Git/GitHub course.

[AdrianDAlessandro]

Yes, I agree. I think the paper analogy makes sense, but the specific examples are difficult to explain in line with that analogy. If you can think of a way to make it work with a recipe in a way that easier to understand, then I say go for it!

I guess an example of what not to do is easier to think of:

• Do not include "preheat oven to 180C" in your Ingredients section, etc

[cc-a]

As a proposed lesson plan:

• Start with the garbled recipe and maybe an exercise where we directly ask people to say what's wrong with it with some leading questions if necessary. Their observations are translated into the principles (e.g. "it's all jumbled up" -> "in software engineering terms we say that it has poor separation of concerns").
• Present a better organised recipe and consider how each of the principles have been applied and made it more intelligible and useful. e.g. having a separated pastry concern means other recipes can refer back to it -> reusing a function.
• A general disclaimer/explainer that we're trying to communicate a set of conceptual tools for thinking about your code structure. How to actually apply them will vary across problems/domains/code bases. We'll try and provide some examples and signs that a particular principle is being violated.
• Sections on each principle that give:
  • a formal definition
  • an easy to understand code example
  • common mistakes/things to watch out for
• A final code based exercise applying the principles.

What do you think?