Session 2 review

episodes/22-example-code.md

@@ -7,7 +7,7 @@ exercises: 0
 :::::::::::::::::::::::::::::::::::::: questions 
 
 - Why should I write readable code?
-- What is a "Code Smell"?
+- What is a "code smell"?
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -19,7 +19,7 @@ exercises: 0
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
-## Obtaining Some Example Code
+## Obtaining Example Code
 
 FIXME: copy code-style-example into softwaresaved org
 
@@ -104,15 +104,24 @@ the code is deliberately written to contain some issues!
 
 ## Why Write Readable Code?
 
-QUESTION: who has seen or used code that looks like this? Yes/No?
-QUESTION: who has written code like this? Yes/No
+
+:::::::::::::::::: discussion
+
+### Readable Code
+
+As a group, answer the following questions:
+
+- Who has seen or used code that looks like this?
+- Who has written code like this?
+
+:::::::::::::::::: 
 
 No one writes great code that's readable, well formatted, and well designed all the time.
 Sometimes you often need to explore ideas with code to understand how the code should be designed,
 and this typically involves trying things out first.
 But... the key is that once you understand how to do something,
 it's a good idea to make sure it's readable and understandable by other people,
-which may includes a future version of yourself,
+which may include a future version of yourself,
 6 months into the future.
 So it's really helpful to end up with good clean code so yit's easier to understand.
 
@@ -131,7 +140,7 @@ you can save yourself (and possibly others) a lot of time later!
 
 :::::::::::::::::::::::::::::::::::::::::  callout
 
-## Does my Code Smell?
+### Does my Code Smell?
 
 Developers sometimes talk about "code smells”.
 Code smells are cursory indications from looking at the source code that a piece of code may have some deeper issues.
@@ -148,7 +157,7 @@ Something to bear in mind when writing code!
 
 Now despite the issues with the code, does it work?
 Let's find out.
-So in the shell, in the root directory of the repository:
+Within the shell, in the root directory of the repository, run the code as follows:
 
 ```bash
 python climate_analysis.py
@@ -168,7 +177,7 @@ Max temperature in Celsius 16.33888888888889 Kelvin 289.4888888888889
 ```
 
 And we can see that the code does indeed appear to work,
-with celsius and kelvin values being printed to the terminal.
+with Celsius and Kelvin values being printed to the terminal.
 But how can we improve its readability?
 We'll use a special tool, called a code linter,
 to help us identify these sorts of issues with the code.

episodes/23-analysing-code.md

@@ -14,7 +14,7 @@ exercises: 0
 
 ::::::::::::::::::::::::::::::::::::: objectives
 
-- Use pylint to verify a program’s adherence to an established Python coding style convention
+- Use Pylint to verify a program’s adherence to an established Python coding style convention
 - Describe the benefits of a virtual environment
 - Create and use a virtual environment to manage Python dependencies separately for our example code
 - Install the Pylint static code analysis tool as a VSCode extension
@@ -26,14 +26,21 @@ exercises: 0
 
 ## Installing a Code Linter
 
-The first thing we need to do is install pylint,
+The first thing we need to do is install Pylint,
 a very well established tool for statically analysing Python code.
 
-Now fortunately, pylint can be installed as a Python package,
-and we're going to create what's known as a virtual environment to hold this installation of pylint.
+Now fortunately, Pylint can be installed as a Python package,
+and we're going to create what's known as a virtual environment to hold this installation of Pylint.
 
-QUESTION: who has installed a Python package before, using the program pip? Yes/No
-QUESTION: who has created and used a Python virtual environment before? Yes/No
+
+:::::::::::::::::::::::::::::::::::::::::::::::: discussion
+
+### Installing Python Packages
+
+Who has installed a Python package before, using the program `pip`?
+Who has created and used a Python virtual environment before?
+
+::::::::::::::::::::::::::::::::::::::::::::::::
 
 ### Benefits of Virtual Environments
 
@@ -64,7 +71,7 @@ Make sure you're in the root directory of the repository, then type
 python -m venv venv
 ```
 
-Here, we're using the built-on Python venv module - short for virtual environment - to create a virtual environment directory called `venv`.
+Here, we're using the built-on Python `venv` module - short for virtual environment - to create a virtual environment directory called "venv".
 We could have called the directory anything, but naming it `venv` (or `.venv`) is a common convention,
 as is creating it within the repository root directory.
 This makes sure the virtual environment is closely associated with this project, and not easily confused with another.
@@ -83,7 +90,15 @@ You should notice the prompt changes to reflect that the virtual environment is
 (venv) $
 ```
 
-QUESTION: who has successfully created and activated their virtual environment? Yes/No?
+
+:::::::::::::::::::::::::::::::::::::::::::::::: instructor
+
+### Setting up a Virtual Environment - Checkin
+
+Who has successfully created and activated their virtual environment?
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
 
 Now it's created, let's take a look at what's in this virtual environment at this point.
 
@@ -123,7 +138,7 @@ which can help our code in many ways:
 
 :::::::::::::::::::::::::::::::::::::::::
 
-So we can install pylint into our virtual environment:
+So we can install `pylint` library into our virtual environment as:
 
 ```bash
 pip install pylint
@@ -151,7 +166,7 @@ tomlkit           0.13.2
 typing_extensions 4.13.1
 ```
 
-So in addition to pylint,
+So in addition to Pylint,
 we see a number of other dependent packages installed that are required by it.
 
 We can also *deactivate* our virtual environment:
@@ -160,7 +175,7 @@ We can also *deactivate* our virtual environment:
 deactivate
 ```
 
-You should see the `(venv)` prefix disappear,
+You should see the "(venv)" prefix disappear,
 indicating we have returned to our global Python environment.
 Let's reactivate it since we'll need it to use pylint.
 
@@ -172,7 +187,7 @@ Let's reactivate it since we'll need it to use pylint.
 
 ## Analysing our Code using a Linter
 
-Let's point pylint at our code and see what it reports:
+Let's point Pylint at our code and see what it reports:
 
 ```bash
 pylint climate_analysis.py
@@ -238,7 +253,13 @@ Which is helpful if we need clarification on a particular message.
 If we now edit the file, and go to line 9, column 35,
 we can see that there is an unnecessary space.
 
-QUESTION: who's managed to run pylint on the example code? Yes/No
+:::::::::::::::::::::::::::::::::::: instructor 
+
+### Running Pylint - Checkin 
+
+Who's managed to run pylint on the example code?
+
+::::::::::::::::::::::::::::::::::::
 
 Let's fix this issue now by removing the space,
 save the changed file,

episodes/24-linter-advanced.md

@@ -8,7 +8,7 @@ exercises: 0
 
 - What can I do to increase the detail of Pylint reports?
 - How can I reduce unwanted messages from Pylint?
-- How can I use static code analysis tools with VSCode?
+- How can I use static code analysis tools within VSCode?
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -58,7 +58,13 @@ Messages
 ...
 ```
 
-QUESTION: for those doing activity, who's managed to run this command? YES/NO
+:::::::::::::::::: instructor
+
+### Pylint Verbose Reporting - Checkin
+
+For those doing activity, who's managed to run this command?
+
+::::::::::::::::::
 
 It gives you some overall statistics,
 plus comparisons with the last time you ran it,
@@ -72,7 +78,7 @@ on aspects such as:
 
 Looking at raw metrics,
 we can see that it breaks down our program into how many lines are
-code lines, python docstrings, standalone comments, and empty lines.
+code lines, Python docstrings, standalone comments, and empty lines.
 This is very useful, since it gives us an idea of how well commented our code is.
 In this case - not very well commented at all!
 For normal comments, the usually accepted wisdom is to add them to explain *why* you are doing something, or perhaps to explain how necessarily complex code works,
@@ -81,7 +87,13 @@ since clearly written code should do that itself.
 
 ## Increasing our Pylint Score - Adding a Docstring
 
-QUESTION: Who's familiar with Python docstrings? Yes/No
+:::::::::::::::::: discussion
+
+### Docstrings
+
+Who's familiar with Python docstrings?
+
+::::::::::::::::::
 
 Docstrings are a special kind of comment for a function,
 that explain what the function does,
@@ -99,7 +111,7 @@ Let's add one to our code now, within the `fahr_to_celsius` function.
     """
 ```
 
-Re-run pylint - can see we have one less docstring error, and a slightly higher score.
+Re-run `pylint` command - can see we have one less docstring error, and a slightly higher score.
 
 If you'd like to know more about docstrings and commenting,
 there's an in-depth [RealPython tutorial](https://realpython.com/documenting-python-code/) on these and the different ways you can format them.
@@ -191,7 +203,7 @@ Every time you re-run it now, the `C0301` issue will not be present.
 ## Using Pylint within VSCode
 
 The good news is that if you're using the VSCode IDE,
-we can also (or alternatively) install a Python linter in VSCode to give us this code analysis functionality, by installing a pylint extension.
+we can also (or alternatively) install a Python linter in VSCode to give us this code analysis functionality, by installing the Pylint extension.
 Select the `Extensions` icon and this time search for `Pylint`, the one by Microsoft, and click `Install`.
 
 Going back to our code you should now find lots of squiggly underlines of various colours.