diff --git a/episodes/22-example-code.md b/episodes/22-example-code.md index 05693410..0a09e698 100644 --- a/episodes/22-example-code.md +++ b/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. diff --git a/episodes/23-analysing-code.md b/episodes/23-analysing-code.md index 486a9a04..5c2e22c5 100644 --- a/episodes/23-analysing-code.md +++ b/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? + +:::::::::::::::::::::::::::::::::::::::::::::::: 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 diff --git a/episodes/24-linter-advanced.md b/episodes/24-linter-advanced.md index 0d46a6bd..763ed7e0 100644 --- a/episodes/24-linter-advanced.md +++ b/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 +:::::::::::::::::: 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. diff --git a/episodes/32-example-code.md b/episodes/32-example-code.md index 075df8d1..6c849774 100644 --- a/episodes/32-example-code.md +++ b/episodes/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 diff --git a/episodes/33-feature-branch.md b/episodes/33-feature-branch.md index 39fc281d..8758b4eb 100644 --- a/episodes/33-feature-branch.md +++ b/episodes/33-feature-branch.md @@ -7,13 +7,13 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::: questions - How do I use Git to create and work on a feature branch? -- How do I push my branch changes to GitHub? +- How do I push my local branch changes to GitHub? :::::::::::::::::::::::::::::::::::::::::::::::: ::::::::::::::::::::::::::::::::::::: objectives -- Create and use new a feature branch in our repository to working on an issue +- Create and use new a feature branch in our repository to work on an issue - Fix issue and commit changes to the feature branch - Push the new branch and its commits to GitHub @@ -126,7 +126,13 @@ Your branch is up-to-date with 'origin/main'. nothing to commit, working tree clean ``` -QUESTION: who's created their new feature branch? Yes/No +:::::::::::::::::: instructor + +### Creating Feature Branch - Checkin + +Who's created their new feature branch? + +:::::::::::::::::: ### Switching to the New Branch @@ -178,7 +184,13 @@ Then add the following to the `FahrToKelvin` function (just below the function d Then save the file. -QUESTION: Who has added this to the file, and saved it? Yes/No +:::::::::::::::::: instructor + +### Changing the File - Checkin + +Who has added this to the file, and saved it? + +:::::::::::::::::: Now we've done this, let's commit this change to the repository on our new branch. @@ -239,7 +251,13 @@ Date: Tue Apr 8 14:47:05 2025 +0100 So, as we can see, on our new feature branch we now have our initial commit inherited from the main branch, and also our two new commits. -QUESTION: who's edited the file and made the changes, and committed them - who's done that twice? Yes/No +:::::::::::::::::: instructor + +### Comming on the Branch - Checkin + +Who's edited the file and made the changes, and committed them - who's done that twice? + +:::::::::::::::::: ## Push New Feature Branch and Commits to GitHub @@ -288,8 +306,15 @@ So here, we're telling git to push the changes on the new branch to a branch wit `origin` here is a shorthand that refers to the originating repository (the one we cloned originally). You'll notice a message suggesting we could create a pull request to merge the changes with the main branch. -QUESTION: who's committed that change and pushed the new branch with its commits to GItHub? Yes/no -Let's do this now! +:::::::::::::::::: instructor + +### Pushing the Feature Branch to GitHub - Checkin + +Who's committed that change and pushed the new branch with its commits to GitHub? +If you have not done it - let's push the feature branch to GitHub now! + +:::::::::::::::::: + ::::::::::::::::::::::::::::::::::::: keypoints diff --git a/episodes/34-pull-request.md b/episodes/34-pull-request.md index 5797eef7..324b2c6b 100644 --- a/episodes/34-pull-request.md +++ b/episodes/34-pull-request.md @@ -53,7 +53,7 @@ So let's go back to our repository on GitHub. You may see a message displayed at the top about protecting the main branch. We may come back to this later, so no need to worry about this for now. -If we select the dropdown where it says "main", it gives us a list of branches. +If we select the dropdown where it says `main`, it gives us a list of branches. We can see all branches by selecting that option at the bottom. Now, we can see we have our new branch that has appeared, which is separate from our main branch. @@ -87,7 +87,15 @@ But we will assign the pull request (or PR for short) to ourselves, since it's a good idea to assign responsibility where we can. So let's create the pull request by selecting the button. -QUESTION: who's created the pull request? Yes/No + +:::::::::::::::::::::::::::::::::::: instructor + +### Creating a Pull Request - Checkin + +Who's created the pull request? + +:::::::::::::::::::::::::::::::::::: + Now we get another screen describing the new PR itself. If we'd assigned any reviewers, we now wait for their reviews of this pull request. diff --git a/episodes/35-merge-pr.md b/episodes/35-merge-pr.md index 9506568d..baaedab9 100644 --- a/episodes/35-merge-pr.md +++ b/episodes/35-merge-pr.md @@ -6,7 +6,7 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::: questions -- How do I merge changes proposed within a pull request? +- How do I merge changes proposed within a pull request with the main branch? - What should I do with a branch that has been merged and is no longer required? :::::::::::::::::::::::::::::::::::::::::::::::: @@ -65,7 +65,14 @@ We can add more information here if needed - but let's `Confirm rebase and merge Note that it says that the merge was done successfully, and suggests we can delete the branch. -QUESTION: who has merged the pull request? Yes/No +:::::::::::::::::::::::::::::::::::: instructor + +### Merging a Pull Request - Checkin + +Who has merged the pull request? + +:::::::::::::::::::::::::::::::::::: + We said earlier that branches in Git should be short lived where possible, and keeping branches hanging around may cause confusion. diff --git a/episodes/36-merge-conflicts.md b/episodes/36-merge-conflicts.md index fc92b92f..14d6ca0e 100644 --- a/episodes/36-merge-conflicts.md +++ b/episodes/36-merge-conflicts.md @@ -20,7 +20,7 @@ exercises: 0 ## Work on Another Issue -Now we still have two remaining issues we can look at. +Now we still have two remaining issues we can look at. Interestingly, both of them require changes that can cause a conflict when merging, so let's look at those now. @@ -133,7 +133,7 @@ And in this case, there is only one conflicting file - `climate_analysis..py`, but there could be more than one. Now we can attempt to resolve the conflict by selecting `Resolve conflicts`. -The GitHub interface is really useful here. +The GitHub interface is really useful here. It tells you which files have the conflicts on the left (only `climate_analysis.py` in this case), and where in each file the conflicts are. So let's fix the conflict.