Review of Thomas's rework of software architecture section by Aleks

_config.yml

@@ -95,10 +95,13 @@ extras_order:
   - discuss
   - protect-main-branch
   - vscode
+  - software-architecture-extra
+  - programming-paradigms
+  - procedural-programming
   - functional-programming
+  - object-oriented-programming
   - persistence
   - databases
-  - verifying-code-style-linters
   - quiz
 # Files and directories that are not to be copied.
 exclude:

_episodes/15-coding-conventions.md

@@ -438,7 +438,7 @@ because an incorrect comment causes more confusion than no comment at all.
 >> which is helpfully marking inconsistencies with coding guidelines by underlying them.
 >> There are a few things to fix in `inflammation-analysis.py`, for example:
 >>
->>  1. Line 24 in `inflammation-analysis.py` is too long and not very readable.
+>>  1. Line 30 in `inflammation-analysis.py` is too long and not very readable.
 >>     A better style would be to use multiple lines and hanging indent,
 >>     with the closing brace `}' aligned either with
 >>     the first non-whitespace character of the last line of list
@@ -487,7 +487,7 @@ because an incorrect comment causes more confusion than no comment at all.
 >>     Note how PyCharm is warning us by underlying the whole line.
 >>
 >>  4. Only one blank line after the end of definition of function `main`
->>     and the rest of the code on line 30 in `inflammation-analysis.py` -
+>>     and the rest of the code on line 33 in `inflammation-analysis.py` -
 >>     should be two blank lines.
 >>     Note how PyCharm is warning us by underlying the whole line.
 >>

_episodes/30-section3-intro.md

@@ -2,7 +2,7 @@
 title: "Section 3: Software Development as a Process"
 colour: "#fafac8"
 start: true
-teaching: 5
+teaching: 10
 exercises: 0
 questions:
 - "How can we design and write 'good' software that meets its goals and requirements?"
@@ -13,7 +13,11 @@ objectives:
 keypoints:
 - "Software engineering takes a wider view of software development beyond programming (or coding)."
 - "Ensuring requirements are sufficiently captured is critical to the success of any project."
-- "Following a process makes development predictable, can save time, and helps ensure each stage of development is given sufficient consideration before proceeding to the next."
+- "Following a process makes software development predictable, saves time in the long run, 
+  and helps ensure each stage of development is given sufficient consideration 
+  before proceeding to the next."
+- "Once you get the hang of a programming language, writing code to do what you want is relatively 
+easy. The hard part is writing code that is easy to adapt when your requirements change."
 ---
 
 In this section, we will take a step back from coding development practices and tools
@@ -65,7 +69,7 @@ Someone who is engineering software takes a wider view:
   but there is an assumption that the software - or even just a part of it -
   could be reused in the future.
 
-### The Software Development Process
+### Software Development Process
 
 The typical stages of a software development process can be categorised as follows:
 
@@ -75,7 +79,7 @@ The typical stages of a software development process can be categorised as follo
   This helps maintain a clear direction throughout development,
   and sets clear targets for what the software needs to do.
 - **Design:** where the requirements are translated into an overall design for the software.
-  It covers what will be the basic software 'components' and how they'll fit together,
+  It covers what will be the basic software 'components' and how they will fit together,
   as well as the tools and technologies that will be used,
   which will together address the requirements identified in the first stage.
 - **Implementation:** the software is developed according to the design,
@@ -99,7 +103,7 @@ these stages are followed implicitly or explicitly in every software project.
 What is required for a project (during requirements gathering) is always considered, for example,
 even if it isn't explored sufficiently or well understood.
 
-Following a process of development offers some major benefits:
+Following a **process** of development offers some major benefits:
 
 - **Stage gating:** a quality *gate* at the end of each stage,
   where stakeholders review the stage's outcomes to decide
@@ -115,31 +119,27 @@ Following a process of development offers some major benefits:
 - **Transparency:** essentially, each stage generates output(s) into subsequent stages,
   which presents opportunities for them to be published
   as part of an open development process.
-- **It saves time:** a well-known result from
+- **Time saving:** a well-known result from
   [empirical software engineering studies](https://web.archive.org/web/20160731150816/http://superwebdeveloper.com/2009/11/25/the-incredible-rate-of-diminishing-returns-of-fixing-software-bugs/)
-  is that it becomes exponentially more expensive to fix mistakes in future stages.
-  For example, if a mistake takes 1 hour to fix in requirements,
+  is that fixing software mistakes is exponentially more expensive in later software development 
+  stages.
+  For example, if a mistake takes 1 hour to fix in the requirements stage,
   it may take 5 times that during design,
   and perhaps as much as 20 times that to fix if discovered during testing.
 
 In this section we will place the actual writing of software (implementation)
-within the context of the typical software development process:
+within the context of a typical software development process:
 
 - Explore the **importance of software requirements**,
-  the different classes of requirements,
+  different classes of requirements,
   and how we can interpret and capture them.
 - How requirements inform and drive the **design of software**,
   the importance, role, and examples of **software architecture**,
   and the ways we can describe a software design.
-- **Implementation choices** in terms of **programming paradigms**,
-  looking at **procedural**, **functional**, and **object oriented** paradigms of development.
-  Modern software will often contain instances of multiple paradigms,
-  so it is worthwhile being familiar with them and knowing when
-  to switch in order to make better code.
-- How you can (and should) assess and update a software's architecture when
-  requirements change and complexity increases -
-  is the architecture still fit for purpose,
-  or are modifications and extensions becoming increasingly difficult to make?
+- How to **improve** existing code to be more **readable**, **testable** and **maintainable**.
+- Consider different strategies for writing well designed code, including
+  using **pure functions**, **classes** and **abstractions**.
+- How to create, assess and improve **software design**.
 
 
 {% include links.md %}

_episodes/31-software-requirements.md

@@ -1,7 +1,7 @@
 ---
 title: "Software Requirements"
-teaching: 15
-exercises: 30
+teaching: 25
+exercises: 15
 questions:
 - "Where do we start when beginning a new software project?"
 - "How can we capture and organise what is required for software to function as intended?"
@@ -22,7 +22,7 @@ The requirements of our software are the basis on which the whole project rests
 if we get the requirements wrong, we'll build the wrong software.
 However, it's unlikely that we'll be able to determine all of the requirements upfront.
 Especially when working in a research context,
-requirements are flexible and may change as we develop our software.
+requirements are flexible and may change as we develop our software.  
 
 ## Types of Requirements
 
@@ -223,17 +223,16 @@ and these aspects should be considered as part of the software's non-functional
 
 > ## Optional Exercise: Requirements for Your Software Project
 >
-> Think back to a piece of code or software (either small or large) you've written,
+> Think back to a piece of code or software (either small or large) you have written,
 > or which you have experience using.
 > First, try to formulate a few of its key business requirements,
-> then derive these into user and then solution requirements
-> (in a similar fashion to the ones above in *Types of Requirements*).
+> then derive these into user and then solution requirements.
 {: .challenge}
 
 
 ### Long- or Short-Lived Code?
 
-Along with requirements, here's something to consider early on.
+Along with requirements, here is something to consider early on.
 You, perhaps with others, may be developing open-source software
 with the intent that it will live on after your project completes.
 It could be important to you that your software is adopted and used by other projects
@@ -249,10 +248,10 @@ so be sure to consider these aspects.
 On the other hand, you might want to knock together some code to prove a concept
 or to perform a quick calculation
 and then just discard it.
-But can you be sure you'll never want to use it again?
-Maybe a few months from now you'll realise you need it after all,
+But can you be sure you will never want to use it again?
+Maybe a few months from now you will realise you need it after all,
 or you'll have a colleague say "I wish I had a..."
-and realise you've already made one.
+and realise you have already made one.
 A little effort now could save you a lot in the future.
 
 ## From Requirements to Implementation, via Design
@@ -269,12 +268,12 @@ At each level, not only are the perspectives different,
 but so are the nature of the objectives and the language used to describe them,
 since they each reflect the perspective and language of their stakeholder group.
 
-It's often tempting to go right ahead and implement requirements within existing software,
+It is often tempting to go right ahead and implement requirements within existing software,
 but this neglects a crucial step:
 do these new requirements fit within our existing design,
 or does our design need to be revisited?
 It may not need any changes at all,
-but if it doesn't fit logically our design will need a bigger rethink
+but if it does not fit logically our design will need a bigger rethink
 so the new requirement can be implemented in a sensible way.
 We'll look at this a bit later in this section,
 but simply adding new code without considering