differences for PR #5

Author: actions-user

12-running-vscode.md

@@ -58,7 +58,7 @@ There are many other features and ways to access them, and we'll cover key ones
 
 Extensions are a major strength of VSCode. Whilst VSCode appears quite lightweight, and presents a simple interface (particularly compared to many other IDEs!), this is quite deceptive.
 You can extend its functionality in many different ways. 
-For example, installing support for other languages, greater support for version control, there's even support for working with databases, and so on.
+or example, installing support for other languages, greater support for version control, there's even support for working with databases, and so on.
 There are literally tens of thousands of possible extensions now.
 
 Now VSCode already comes with built-in support for JavaScript, including TypeScript and node.js,
@@ -67,24 +67,24 @@ Installing a language extension will allow you to do more things with that parti
 
 Let's install an extension now:
 
-1. Firstly, select the extensions icon, then type in "Python" into the search box at the top, and it'll give you a list of all Python-related extensions.
+1. Firstly, select the extensions icon first, then type in Python into the search box at the top, and it'll give you a list of all python-related extensions.
 1. Select the one which says `Python` from Microsoft. This is the Microsoft official Python extension.
 1. Then select `Install`.
 
 It might take a minute - you can see a sliding blue line in the top left to indicate it's working.
 Once complete, you should see a couple of "Welcome" windows introducing you to two of its key features - support for Python and Jupyter notebooks.
 If you use Jupyter notebooks, which is a way of writing Python programs that you can run line by line from within an editor as you write the program, you may find this useful.
 
-For now, let's configure this extension for our Python development, and to do that, we need to tell VSCode which Python installation on our machine we'd like it to use. In the Python Welcome window, select `Select a Python interpreter`, and then `Select Python interpreter`.
-You may find you have many installations of Python, or only have one. Try to select the version later than 3.8 if you can.
-Then select `Mark done`, and close the Welcome window.
+For now, let's configure this extension for our Python development, and to do that, we need to do is tell VSCode which Python installation on our machine we'd like it to use. In the Python Welcome window, select `Select a Python interpreter`, and then `Select Python interpreter`.
+You may find you have many installations of Python, or only have one. Try to select one later than 3.8 if you can.
+Then select `Mark done`, and close the welcome windows.
 
 ## A Sample Project
 
 FIXME: copy code-style-example repo to softwaresaved's organisation
 
 Next, let's obtain some example Python and edit it from within VSCode.
-First, download the example code we'll use from https://github.com/UNIVERSE-HPC/code-style-example/releases/tag/v1.0.0, either as a `.zip` or `.tar.gz` compressed archive file.
+So first, you can download the example code we'll use from https://github.com/UNIVERSE-HPC/code-style-example/releases/tag/v1.0.0, either as a `.zip` or `.tar.gz` compressed archive file.
 If you're unsure, download the `.zip` file.
 Then, extract all the files from the archive into a convenient location.
 You should see files contained within a new directory named `code-style-example-1.0.0`.
@@ -103,9 +103,9 @@ Note that we're looking for the *folder* that contains the files, not a specific
 
 If your system has the Git version control system installed, you may see a `Clone Repository` option here too.
 If you are familiar with Git and wish to use this option instead,
-select it and enter the repository's location as `https://github.com/UNIVERSE-HPC/code-style-example`.
+select this option instead and enter the repository's location as `https://github.com/UNIVERSE-HPC/code-style-example`.
 Then use the file browser that is presented to find a convenient location to store the cloned code and click on `Select as Repository Destination`,
-then select `Open` when ‘Would you like to open the cloned repository?' popup appears.
+then select `Open` when ‘Would you like to open the cloned repository?' appears.
 
 :::::::::::::::::::::::::::::::::::::::::
 
@@ -126,7 +126,7 @@ So next, let's look at editing code.
 
 ::::::::::::::::::::::::::::::::::::: keypoints 
 
-- Key VSCode features are accessible via the left navigation bar and the menu
+- Key VSCode features are accessible via the left navigation bar and the menu.
 - VSCode's capabilities can be increased by installing extensions
 - Language-specific support is available via extensions
 - A VSCode "workspace" is a project that consists of a collection of folder and files

13-code-editor.md

@@ -41,7 +41,7 @@ But in essence, the code is designed to do the following:
 1. Open a file in the CSV (comma separated value) format
 1. Go through the file line by line, and:
    - If the line begins with a `#` symbol, ignore it.
-   - Otherwise, extract the fourth column (which contains temperature in Fahrenheit), convert it to Celsius and Kelvin, and output those readings.
+   - Otherwise, extract the fourth column (which is in Fahrenheit), convert it to Celsius and Kelvin, and output those readings.
 
 Let's take a look at some of what the code editor gives us.
 

14-running-debugging.md

@@ -25,8 +25,8 @@ exercises: 0
 
 ## Running Python in VSCode
 
-Now let's try running a Python script.
-First, make sure your Python code doesn't have any errors!
+Now let's try running a Python file.
+First, make sure your Python doesn't have any errors!
 Then, select the "Play"-looking icon at the top right of the code editor.
 
 FIXME: screenshot snippet of the play icon?
@@ -147,9 +147,7 @@ FIXME: show screenshot snippet of debugging icons
 - The first one is continue, which allows the script to keep running until the next breakpoint.
 - The next one allows us to step over - or through - the script one statement at a time.
 - The next two allow us to choose to step into or out of a function call, which is interesting.
-  
 If we want to examine the inner workings of a function during this debug session, we can do that.
-
 - The green cycle one is to restart the debug process.
 - The red cross stops debugging completely.
 
@@ -161,7 +159,7 @@ If we step again, and then again, our program halts because it's run into the pr
 
 This tells us something useful - that the problem occurs in the first iteration of the loop.
 So, this implies, the problem might be with the first line of data being processed,
-since the Python code is going through the data file line by line.
+since the Python is going through the data file line by line.
 If we re-run the debugger, we can go through this process again.
 And we can see something interesting when we get to the `if` statement.
 From the code, we know that the if statement is looking for an exclamation mark at the beginning of the line to indicate a comment.

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.

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?
+
+:::::::::::::::::::::::::::::::::::::::::::::::: discussion
+
+### Setting up a Virtual Environment - Check In
+
+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

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
+:::::::::::::::::: discussion
+
+### 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 - Checkin
+
+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.

32-example-code.md

@@ -29,8 +29,8 @@ For this lesson we'll need to create a new GitHub repository based on the conten
 
 1. Once logged into GitHub in a web browser,
 go to https://github.com/UNIVERSE-HPC/git-example.
-1. Select 'Use this template', and then select 'Create a new repository' from the dropdown menu.
-1. On the next screen, ensure your personal GitHub account is selected in the `Owner` field, and fill in `Repository name` with `git-example`.
+1. Select `Use this template`, and then select `Create a new repository` from the dropdown menu.
+1. On the next screen, ensure your personal GitHub account is selected in the `Owner` field, and fill in `Repository name` with "git-example".
 1. Ensure the repository is set to `Public`.
 1. Select `Create repository`.
 
@@ -157,17 +157,17 @@ so select `Assign yourself`.
 
 :::: challenge
 
-## Adding Work for Ourselves
+### Adding Work for Ourselves
+
+Repeat the process of adding issues on your GitHub repository for the following two issues in this order:
 
-Repeat this process for the other two issues in the following order:
 - "Add missing docstrings to function and module"
 - "Script fails with undefined function name error"
+
 We'll refer back to these issues later!
 
 ::::
 
-QUESTION: who's created the three issues? Yes/No
-
 
 ::::::::::::::::::::::::::::::::::::: keypoints