diff --git a/config.yaml b/config.yaml index 284cb92d2..8d1572da8 100644 --- a/config.yaml +++ b/config.yaml @@ -64,7 +64,7 @@ contact: 'info@software.ac.uk' # - another-learner.md # Order of episodes in your lesson -episodes: +episodes: - 00-setting-the-scene.md - 10-section1-intro.md - 11-software-project.md @@ -97,12 +97,10 @@ episodes: - 60-wrap-up.md # Information for Learners -learners: +learners: - quiz.md -- learner-setup.md +- installation-instructions.md - common-issues.md -- reference.md -- vscode.md - software-architecture-extra.md - programming-paradigms.md - procedural-programming.md @@ -110,13 +108,15 @@ learners: - object-oriented-programming.md - persistence.md - databases.md +- vscode.md +- reference.md # Information for Instructors -instructors: +instructors: - instructor-notes.md # Learner Profiles -profiles: +profiles: # Customisation --------------------------------------------- # diff --git a/episodes/10-section1-intro.md b/episodes/10-section1-intro.md index d9cef0ed6..9d0e4ea0e 100644 --- a/episodes/10-section1-intro.md +++ b/episodes/10-section1-intro.md @@ -1,7 +1,5 @@ --- title: 'Section 1: Setting Up Environment For Collaborative Code Development' -colour: '#fafac8' -start: yes teaching: 10 exercises: 0 --- diff --git a/episodes/11-software-project.md b/episodes/11-software-project.md index c2953ff7d..2a66ddacb 100644 --- a/episodes/11-software-project.md +++ b/episodes/11-software-project.md @@ -1,5 +1,5 @@ --- -title: Introduction to Our Software Project +title: 1.1 Introduction to Our Software Project teaching: 20 exercises: 10 --- diff --git a/episodes/12-virtual-environments.md b/episodes/12-virtual-environments.md index 180fc517c..afa971423 100644 --- a/episodes/12-virtual-environments.md +++ b/episodes/12-virtual-environments.md @@ -1,5 +1,5 @@ --- -title: Virtual Environments For Software Development +title: 1.2 Virtual Environments For Software Development start: no teaching: 30 exercises: 0 diff --git a/episodes/13-ides.md b/episodes/13-ides.md index efa7168d6..5324931f3 100644 --- a/episodes/13-ides.md +++ b/episodes/13-ides.md @@ -1,5 +1,5 @@ --- -title: Integrated Software Development Environments +title: 1.3 Integrated Software Development Environments start: no teaching: 25 exercises: 10 diff --git a/episodes/14-collaboration-using-git.md b/episodes/14-collaboration-using-git.md index 32b9049f5..23ca9d868 100644 --- a/episodes/14-collaboration-using-git.md +++ b/episodes/14-collaboration-using-git.md @@ -1,5 +1,5 @@ --- -title: Software Development Using Git and GitHub +title: 1.4 Software Development Using Git and GitHub start: no teaching: 35 exercises: 0 diff --git a/episodes/15-coding-conventions.md b/episodes/15-coding-conventions.md index 61062ad89..aa77c0517 100644 --- a/episodes/15-coding-conventions.md +++ b/episodes/15-coding-conventions.md @@ -1,6 +1,5 @@ --- -title: Python Code Style Conventions -start: no +title: 1.5 Python Code Style Conventions teaching: 20 exercises: 20 --- @@ -29,7 +28,8 @@ to make sure that your code is consistently formatted and readable by yourself a > *"Any fool can write code that a computer can understand. > Good programmers write code that humans can understand."* -> - [Martin Fowler](https://en.wikiquote.org/wiki/Martin_Fowler), British software engineer, author and international speaker on software development +> +> --- [Martin Fowler](https://en.wikiquote.org/wiki/Martin_Fowler), British software engineer, author and international speaker on software development ## Python Coding Style Guide diff --git a/episodes/16-verifying-code-style-linters.md b/episodes/16-verifying-code-style-linters.md index 2cdae3a95..5a9ad6f8d 100644 --- a/episodes/16-verifying-code-style-linters.md +++ b/episodes/16-verifying-code-style-linters.md @@ -1,6 +1,5 @@ --- -title: Verifying Code Style Using Linters -start: no +title: 1.6 Verifying Code Style Using Linters teaching: 15 exercises: 5 --- diff --git a/episodes/17-section1-optional-exercises.md b/episodes/17-section1-optional-exercises.md index 0473ceccf..f9b169118 100644 --- a/episodes/17-section1-optional-exercises.md +++ b/episodes/17-section1-optional-exercises.md @@ -1,5 +1,5 @@ --- -title: Optional Exercises for Section 1 +title: 1.7 Optional Exercises for Section 1 start: no teaching: 0 exercises: 45 diff --git a/episodes/20-section2-intro.md b/episodes/20-section2-intro.md index 01a5db96f..58a8af6ec 100644 --- a/episodes/20-section2-intro.md +++ b/episodes/20-section2-intro.md @@ -1,7 +1,5 @@ --- title: 'Section 2: Ensuring Correctness of Software at Scale' -colour: '#fafac8' -start: yes teaching: 5 exercises: 0 --- diff --git a/episodes/21-automatically-testing-software.md b/episodes/21-automatically-testing-software.md index b4e5dd8d3..8e607804c 100644 --- a/episodes/21-automatically-testing-software.md +++ b/episodes/21-automatically-testing-software.md @@ -1,5 +1,5 @@ --- -title: Automatically Testing Software +title: 2.1 Automatically Testing Software teaching: 30 exercises: 15 --- diff --git a/episodes/22-scaling-up-unit-testing.md b/episodes/22-scaling-up-unit-testing.md index 904482aa8..0831600af 100644 --- a/episodes/22-scaling-up-unit-testing.md +++ b/episodes/22-scaling-up-unit-testing.md @@ -1,5 +1,5 @@ --- -title: Scaling Up Unit Testing +title: 2.2 Scaling Up Unit Testing teaching: 10 exercises: 5 --- diff --git a/episodes/23-continuous-integration-automated-testing.md b/episodes/23-continuous-integration-automated-testing.md index 89156fd0f..215faef16 100644 --- a/episodes/23-continuous-integration-automated-testing.md +++ b/episodes/23-continuous-integration-automated-testing.md @@ -1,5 +1,5 @@ --- -title: Continuous Integration for Automated Testing +title: 2.3 Continuous Integration for Automated Testing teaching: 45 exercises: 0 --- @@ -366,7 +366,7 @@ jobs: python-version: ["3.10", "3.11"] # Here we add the reference to the os matrix values - runs-on: {% raw %}${{ matrix.os }}{% endraw %} + runs-on: ${{ matrix.os }} # Same key-value pairs as in "Defining Our Workflow" section steps: @@ -378,7 +378,7 @@ jobs: uses: actions/setup-python@v5 with: # Here we add the reference to the python-version matrix values - python-version: {% raw %}${{ matrix.python-version }}{% endraw %} + python-version: ${{ matrix.python-version }} # Same steps as in "Defining Our Workflow" section - name: Install Python dependencies run: | @@ -389,7 +389,7 @@ jobs: python3 -m pytest --cov=catchment.models tests/test_models.py ``` -The `{% raw %}${{ }}{% endraw %}` are used +The `{{ }}` are used as a means to reference configuration values from the matrix. This way, every possible permutation of Python versions 3.10 and 3.11 with the latest versions of Ubuntu, Mac OS and Windows operating systems diff --git a/episodes/24-diagnosing-issues-improving-robustness.md b/episodes/24-diagnosing-issues-improving-robustness.md index ac1d627e2..40ad7bc9f 100644 --- a/episodes/24-diagnosing-issues-improving-robustness.md +++ b/episodes/24-diagnosing-issues-improving-robustness.md @@ -1,5 +1,5 @@ --- -title: Diagnosing Issues and Improving Robustness +title: 2.4 Diagnosing Issues and Improving Robustness teaching: 30 exercises: 15 --- diff --git a/episodes/25-section2-optional-exercises.md b/episodes/25-section2-optional-exercises.md index 4f2397822..664f39bf1 100644 --- a/episodes/25-section2-optional-exercises.md +++ b/episodes/25-section2-optional-exercises.md @@ -1,5 +1,5 @@ --- -title: Optional Exercises for Section 2 +title: 2.5 Optional Exercises for Section 2 start: no teaching: 0 exercises: 45 diff --git a/episodes/30-section3-intro.md b/episodes/30-section3-intro.md index 607588a95..8ddba6251 100644 --- a/episodes/30-section3-intro.md +++ b/episodes/30-section3-intro.md @@ -1,7 +1,5 @@ --- title: 'Section 3: Software Development as a Process' -colour: '#fafac8' -start: yes teaching: 10 exercises: 0 --- @@ -23,7 +21,9 @@ exercises: 0 In this section, we will take a step back from coding development practices and tools and look at the bigger picture of software as a *process* of development. -> *"If you fail to plan, you are planning to fail."* - Benjamin Franklin +> *"If you fail to plan, you are planning to fail."* +> +> --- Benjamin Franklin ![](fig/section3-overview.svg){alt='Software design and architecture overview flowchart'} diff --git a/episodes/31-software-requirements.md b/episodes/31-software-requirements.md index f20be54f0..0a0d4e56d 100644 --- a/episodes/31-software-requirements.md +++ b/episodes/31-software-requirements.md @@ -1,5 +1,5 @@ --- -title: Software Requirements +title: 3.1 Software Requirements teaching: 25 exercises: 15 --- diff --git a/episodes/32-software-architecture-design.md b/episodes/32-software-architecture-design.md index c607b47a4..f15dc89ff 100644 --- a/episodes/32-software-architecture-design.md +++ b/episodes/32-software-architecture-design.md @@ -1,5 +1,5 @@ --- -title: Software Architecture and Design +title: 3.2 Software Architecture and Design teaching: 25 exercises: 25 --- diff --git a/episodes/33-code-decoupling-abstractions.md b/episodes/33-code-decoupling-abstractions.md index 2fb4c2f30..616741b74 100644 --- a/episodes/33-code-decoupling-abstractions.md +++ b/episodes/33-code-decoupling-abstractions.md @@ -1,5 +1,5 @@ --- -title: Code Decoupling & Abstractions +title: 3.3 Code Decoupling & Abstractions teaching: 30 exercises: 45 --- diff --git a/episodes/34-code-refactoring.md b/episodes/34-code-refactoring.md index 9e534bb36..244427bce 100644 --- a/episodes/34-code-refactoring.md +++ b/episodes/34-code-refactoring.md @@ -1,5 +1,5 @@ --- -title: Code Refactoring +title: 3.4 Code Refactoring teaching: 30 exercises: 20 --- diff --git a/episodes/35-software-architecture-revisited.md b/episodes/35-software-architecture-revisited.md index e9472468b..000748bc7 100644 --- a/episodes/35-software-architecture-revisited.md +++ b/episodes/35-software-architecture-revisited.md @@ -1,5 +1,5 @@ --- -title: Software Architecture Revisited +title: 3.5 Software Architecture Revisited teaching: 15 exercises: 30 --- diff --git a/episodes/40-section4-intro.md b/episodes/40-section4-intro.md index abbccb625..c7b97a249 100644 --- a/episodes/40-section4-intro.md +++ b/episodes/40-section4-intro.md @@ -1,7 +1,5 @@ --- title: 'Section 4: Collaborative Software Development for Reuse' -colour: '#fafac8' -start: yes teaching: 5 exercises: 0 --- @@ -48,46 +46,44 @@ using **Poetry** to manage our Python dependencies and produce a code package we can use with a Python package indexing service to illustrate these principles. -{% comment %} -![](fig/section4-overview.png){alt='Software design and architecture' .image-with-shadow width="800px" } -{% endcomment %} - ![](fig/section4-overview.svg){alt='Software design and architecture' .image-with-shadow width="1000px" } -{% comment %} + B(2. Verifying +-> B(2. Verifying software correctness) -\--> C(3. Software development +-> C(3. Software development as a process) -\--> D(4. Collaborative +-> D(4. Collaborative development for reuse -``` -- Code review -- Software documentation -- Software packaging & release -) -``` - -\--> E(5. Managing software + - Code review + - Software documentation + - Software packaging & release + ) +-> E(5. Managing software over its lifetime) - -{% endcomment %} +--> -{% comment %} + :::::::::::::::::::::::::::::::::::::::: keypoints diff --git a/episodes/41-code-review.md b/episodes/41-code-review.md index 1b82ba8ee..694784d76 100644 --- a/episodes/41-code-review.md +++ b/episodes/41-code-review.md @@ -1,5 +1,5 @@ --- -title: 'Developing Software In a Team: Code Review' +title: '4.1 Developing Software In a Team: Code Review' teaching: 30 exercises: 30 --- @@ -181,7 +181,7 @@ have not seen before. Here is an outline of the process of a tool assisted code review. -{% comment %} + + ![](fig/code-review-sequence-diagram.svg){alt='Code review process sequence' .image-with-shadow width="600px"} Recall [solution requirement SR1.1.1](31-software-requirements.md) diff --git a/episodes/42-software-reuse.md b/episodes/42-software-reuse.md index 98194f8f1..ca2b67f8f 100644 --- a/episodes/42-software-reuse.md +++ b/episodes/42-software-reuse.md @@ -1,5 +1,5 @@ --- -title: Preparing Software for Reuse and Release +title: 4.2 Preparing Software for Reuse and Release start: no teaching: 35 exercises: 15 diff --git a/episodes/43-software-release.md b/episodes/43-software-release.md index 9fb9be05f..d66f5a421 100644 --- a/episodes/43-software-release.md +++ b/episodes/43-software-release.md @@ -1,5 +1,5 @@ --- -title: Packaging Code for Release and Distribution +title: 4.3 Packaging Code for Release and Distribution teaching: 0 exercises: 20 --- diff --git a/episodes/50-section5-intro.md b/episodes/50-section5-intro.md index 9145413ab..7c5a01417 100644 --- a/episodes/50-section5-intro.md +++ b/episodes/50-section5-intro.md @@ -1,7 +1,5 @@ --- title: 'Section 5: Managing and Improving Software Over Its Lifetime' -colour: '#fafac8' -start: yes teaching: 5 exercises: 0 --- @@ -32,34 +30,33 @@ how the outside world interacts with and makes use of our software, how others can interact with ourselves to report issues, and the ways we can successfully manage software improvement in response to feedback. -{% comment %} -![](fig/section5-overview.png){alt='Managing software' .image-with-shadow width="800px" } -{% endcomment %} - ![](fig/section5-overview.svg){alt='Managing software' .image-with-shadow width="1000px" } -{% comment %} + B(2. Verifying +-> B(2. Verifying software correctness) -\--> C(3. Software development +-> C(3. Software development as a process) -\--> D(4. Collaborative +-> D(4. Collaborative development for reuse) -\--> E(5. Managing software +-> E(5. Managing software over its lifetime -``` -- Issue reporting & prioritisation -- Agile development in sprints -- software project management -``` - + - Issue reporting & prioritisation + - Agile development in sprints + - software project management ) - -{% endcomment %} + +--> In this section we will: @@ -79,13 +76,13 @@ In this section we will: -{% comment %} + :::::::::::::::::::::::::::::::::::::::: keypoints diff --git a/episodes/51-managing-software.md b/episodes/51-managing-software.md index 2a5526efb..8e372bb23 100644 --- a/episodes/51-managing-software.md +++ b/episodes/51-managing-software.md @@ -1,5 +1,5 @@ --- -title: Managing a Collaborative Software Project +title: 5.1 Managing a Collaborative Software Project teaching: 15 exercises: 20 --- diff --git a/episodes/52-assessing-software-suitability-improvement.md b/episodes/52-assessing-software-suitability-improvement.md index e6124cbfa..ed838ea06 100644 --- a/episodes/52-assessing-software-suitability-improvement.md +++ b/episodes/52-assessing-software-suitability-improvement.md @@ -1,5 +1,5 @@ --- -title: Assessing Software for Suitability and Improvement +title: 5.2 Assessing Software for Suitability and Improvement teaching: 15 exercises: 30 --- diff --git a/episodes/53-improvement-through-feedback.md b/episodes/53-improvement-through-feedback.md index 2a5769164..8fd79cdee 100644 --- a/episodes/53-improvement-through-feedback.md +++ b/episodes/53-improvement-through-feedback.md @@ -1,5 +1,5 @@ --- -title: Software Improvement Through Feedback +title: 5.3 Software Improvement Through Feedback teaching: 25 exercises: 45 --- @@ -231,8 +231,7 @@ e.g. "Tidy up documentation" or "version 0.1". :::::::::::::::::::::::::::::::::::::::::::::::::: -{% comment %} - + ## Using Sprints to Organise and Work on Issues diff --git a/episodes/60-wrap-up.md b/episodes/60-wrap-up.md index bfd7b2936..3a3f73a5c 100644 --- a/episodes/60-wrap-up.md +++ b/episodes/60-wrap-up.md @@ -1,8 +1,5 @@ --- title: Wrap-up -start: yes -type: wrap-up -colour: '#FBED65' teaching: 15 exercises: 0 --- @@ -20,7 +17,7 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::::::::::::::: -{% comment %} + ## Summary @@ -141,9 +138,9 @@ Below are some additional resources to help you continue learning: - [Additional episode on persisting data](../learners/persistence.md) - [Additional episode on databases](../learners/databases.md) -- [CodeRefinery courses on FAIR - (Findable, Accessible, Interoperable, and Reusable) - software practices][coderefinery-lessons] +- [Additional episode on software architecture](../learners/software-architecture-extra.md) +- [Additional episode on programming paradigms](../learners/programming-paradigms.md) +- [CodeRefinery lessons][coderefinery-lessons] on writing software for open and reproducible research - [Python documentation][python-documentation] - [GitHub Actions documentation][github-actions] diff --git a/learners/databases.md b/learners/databases.md index 11604573d..effa5b10d 100644 --- a/learners/databases.md +++ b/learners/databases.md @@ -1,16 +1,18 @@ --- -title: Databases +title: "Extra Content: Databases" teaching: 30 exercises: 30 -questions: How can we persist complex structured data for efficient access? -objectives: +--- + +::: questions +- How can we persist complex structured data for efficient access? +::: + +::: objectives - Describe the structure of a relational database - Store and retrieve structured data using an Object Relational Mapping (ORM) -keypoints: Relational databases are often the best persistence mechanism for data - which fits well to the Object Oriented paradigm. ---- +::: -## Databases ::::::::::::::::::::::::::::::::::::::::: callout @@ -432,7 +434,7 @@ by moving it into one or more functions at the top of the test file. We have added the ability to store patient records in the database, but not actually connected it to any useful views. there is a common pattern in data management software -which is often refered to as **CRUD** - Create, Read, Update, Delete. +which is often referred to as **CRUD** - Create, Read, Update, Delete. These are the four fundamental views that we need to provide to allow people to manage their data effectively. @@ -464,3 +466,7 @@ will be useful to you here. :::::::::::::::::::::::::::::::::::::::::::::::::: +::: keypoints +- Relational databases are often the best persistence mechanism for data +which fits well to the Object Oriented paradigm. +::: diff --git a/learners/functional-programming.md b/learners/functional-programming.md index 0a32fc858..3fb21a7ed 100644 --- a/learners/functional-programming.md +++ b/learners/functional-programming.md @@ -1,34 +1,21 @@ --- -title: Functional Programming +title: "Extra Content: Functional Programming" teaching: 30 exercises: 30 -questions: +--- + +::: questions - What is functional programming? - Which situations/problems is functional programming well suited for? -objectives: +::: + +::: objectives - Describe the core concepts that define the functional programming paradigm - Describe the main characteristics of code that is written in functional programming style - Learn how to generate and process data collections efficiently using MapReduce and Python's comprehensions -keypoints: -- Functional programming is a programming paradigm where programs are constructed - by applying and composing smaller and simple functions into more complex ones (which - describe the flow of data within a program as a sequence of data transformations). -- In functional programming, functions tend to be *pure* - they do not exhibit *side-effects* - (by not affecting anything other than the value they return or anything outside - a function). Functions can also be named, passed as arguments, and returned from - other functions, just as any other data type. -- MapReduce is an instance of a data generation and processing approach, in particular - suited for functional programming and handling Big Data within parallel and distributed - environments. -- Python provides comprehensions for lists, dictionaries, sets and generators - a - concise (if not strictly functional) way to generate new data from existing data - collections while performing sophisticated mapping, filtering and conditional logic - on original dataset's members. ---- - -## Introduction +::: Functional programming is a programming paradigm where programs are constructed by applying and composing/chaining **functions**. @@ -874,3 +861,19 @@ Took 0.124199753 seconds :::::::::::::::::::::::::::::::::::::::::::::::::: +::: keypoints +- Functional programming is a programming paradigm where programs are constructed + by applying and composing smaller and simple functions into more complex ones (which + describe the flow of data within a program as a sequence of data transformations). +- In functional programming, functions tend to be *pure* - they do not exhibit *side-effects* + (by not affecting anything other than the value they return or anything outside + a function). Functions can also be named, passed as arguments, and returned from + other functions, just as any other data type. +- MapReduce is an instance of a data generation and processing approach, in particular + suited for functional programming and handling Big Data within parallel and distributed + environments. +- Python provides comprehensions for lists, dictionaries, sets and generators - a + concise (if not strictly functional) way to generate new data from existing data + collections while performing sophisticated mapping, filtering and conditional logic + on original dataset's members. +::: diff --git a/learners/learner-setup.md b/learners/installation-instructions.md similarity index 98% rename from learners/learner-setup.md rename to learners/installation-instructions.md index 349bfaa01..50f57d664 100644 --- a/learners/learner-setup.md +++ b/learners/installation-instructions.md @@ -1,11 +1,10 @@ --- -title: Learner Setup +title: Installation Instructions --- -You will need the following software installed and working correctly on your system to be able -to follow the course. +You will need the following software and accounts setup to be able to follow the course: -- [Command line tool](#command-line-tool) (such as **Bash**, **Zsh** or **Git Bash**) +- [Command line tool](#command-line-tool) (such as Bash, Zsh or Git Bash) - [Git version control program](#git-version-control-tool) - [GitHub account](#github-account) - [Python 3 distribution](#python-3-distribution) diff --git a/learners/object-oriented-programming.md b/learners/object-oriented-programming.md index 3d38041d8..a2a9c6094 100644 --- a/learners/object-oriented-programming.md +++ b/learners/object-oriented-programming.md @@ -1,27 +1,21 @@ --- -title: Object Oriented Programming +title: "Extra Content: Object Oriented Programming" teaching: 30 exercises: 35 -questions: +--- + +::: questions: - How can we use code to describe the structure of data? - How should the relationships between structures be described? -objectives: +::: + +::: objectives - Describe the core concepts that define the object oriented paradigm - Use classes to encapsulate data within a more complex program - Structure concepts within a program in terms of sets of behaviour - Identify different types of relationship between concepts within a program - Structure data within a program using these relationships -keypoints: -- Object oriented programming is a programming paradigm based on the concept of classes, - which encapsulate data and code. -- Classes allow us to organise data into distinct concepts. -- By breaking down our data into classes, we can reason about the behaviour of parts - of our data. -- Relationships between concepts can be described using inheritance (*is a*) and composition - (*has a*). ---- - -## Introduction +::: Object oriented programming is a programming paradigm based on the concept of objects, which are data structures that contain (encapsulate) data and code. @@ -915,5 +909,13 @@ class Patient(Person): :::::::::::::::::::::::::::::::::::::::::::::::::: - +::: keypoints +- Object oriented programming is a programming paradigm based on the concept of classes, + which encapsulate data and code. +- Classes allow us to organise data into distinct concepts. +- By breaking down our data into classes, we can reason about the behaviour of parts + of our data. +- Relationships between concepts can be described using inheritance (*is a*) and composition + (*has a*). +::: diff --git a/learners/persistence.md b/learners/persistence.md index 7d933f451..b20ec956e 100644 --- a/learners/persistence.md +++ b/learners/persistence.md @@ -1,11 +1,15 @@ --- -title: Persistence +title: "Extra Content: Persistence" teaching: 25 exercises: 25 -questions: +--- + +::: questions - How can we store and transfer structured data? - How can we make it easier to substitute new components into our software? -objectives: +::: + +::: objectives - Describe how the environment in which software is used may constrain its design. - Identify common components of multi-layer software projects. - Define serialisation and deserialisation. @@ -13,19 +17,7 @@ objectives: - Define what is meant by a contract in the context of Object Oriented design. - Explain the benefits of contracts and implement software components which fulfill them. -keypoints: -- Planning software projects in advance can save a lot of effort later - even a partial - plan is better than no plan at all. -- The environment in which users run our software has an effect on many design choices - we might make. -- By breaking down our software into components with a single responsibility, we avoid - having to rewrite it all when requirements change. -- These components can be as small as a single function, or be a software package - in their own right. -- When writing software used for research, requirements *always* change. ---- - -## Introduction +::: ::::::::::::::::::::::::::::::::::::::::: callout @@ -435,6 +427,16 @@ Can you think of any cases when a CSV might not be a suitable format to hold our :::::::::::::::::::::::::::::::::::::::::::::::::: - +::: keypoints +- Planning software projects in advance can save a lot of effort later - even a partial + plan is better than no plan at all. +- The environment in which users run our software has an effect on many design choices + we might make. +- By breaking down our software into components with a single responsibility, we avoid + having to rewrite it all when requirements change. +- These components can be as small as a single function, or be a software package + in their own right. +- When writing software used for research, requirements *always* change. +::: diff --git a/learners/procedural-programming.md b/learners/procedural-programming.md index bd5e84d10..8741bf785 100644 --- a/learners/procedural-programming.md +++ b/learners/procedural-programming.md @@ -1,17 +1,19 @@ --- -title: Procedural Programming +title: "Extra Content: Procedural Programming" teaching: 10 exercises: 0 -questions: +--- + +::: questions - What is procedural programming? - Which situations/problems is procedural programming well suited for? -objectives: +::: +::: objectives - Describe the core concepts that define the procedural programming paradigm - Describe the main characteristics of code that is written in procedural programming style -keypoints: Procedural Programming emphasises a structured approach to coding, using - a sequence of tasks and subroutines to create a well-organised program. ---- +::: + In procedural programming code is grouped into procedures (also known as routines - reusable piece of code that performs a specific action but @@ -70,4 +72,7 @@ preferred for larger and more complex projects, especially when working in a tea Functional programming can offer more elegant and scalable solutions for complex problems, particularly in parallel computing. - +::: keypoints: +- Procedural Programming emphasises a structured approach to coding, using + a sequence of tasks and subroutines to create a well-organised program. +::: diff --git a/learners/programming-paradigms.md b/learners/programming-paradigms.md index b05109d8c..86b5ebcf9 100644 --- a/learners/programming-paradigms.md +++ b/learners/programming-paradigms.md @@ -1,18 +1,18 @@ --- -title: Programming Paradigms +title: "Extra Content: Programming Paradigms" teaching: 20 exercises: 0 -questions: What should we consider when designing software? -objectives: Describe some of the major software paradigms we can use to classify programming - languages. -keypoints: -- A software paradigm describes a way of structuring or reasoning about code. -- Different programming languages are suited to different paradigms. -- Different paradigms are suited to solving different classes of problems. -- A single piece of software will often contain instances of multiple paradigms. --- -## Programming Paradigms + +::: questions: +- What should we consider when designing software? +::: + +::: objectives: +- Describe some of the major software paradigms we can use to classify programming languages. +::: + In addition to [architectural decisions](../learners/software-architecture-extra.md) on bigger components of your code, it is important to understand the wider landscape of programming paradigms and languages, @@ -159,5 +159,10 @@ have a closer look at [Functional](../learners/functional-programming.md) and in extra episodes and how they can affect our architectural design choices. - +::: keypoints +- A software paradigm describes a way of structuring or reasoning about code. +- Different programming languages are suited to different paradigms. +- Different paradigms are suited to solving different classes of problems. +- A single piece of software will often contain instances of multiple paradigms. +::: diff --git a/learners/setup.md b/learners/setup.md index cb0981d08..8f8858d1d 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -1,11 +1,16 @@ -::: callout +--- +title: Setup +--- ## Setup -Please make sure that you have all the necessary software and accounts setup ahead of the workshop -as described in the [Setup](learners/learner-setup.md) section. -Also check the list of [common issues, fixes \& tips](learners/common-issues.md) -if you experience any problems running any of the tools you installed - -your issue may be solved there. +You will need the following software and accounts setup to be able to follow the course: -::: +- Command line tool (such as Bash, Zsh or Git Bash) +- Git version control program +- GitHub account +- Python 3 distribution +- PyCharm integrated development environment (IDE) + +Please follow the [installation instructions](installation-instructions.md) to install the above tools and +set up for the course. diff --git a/learners/software-architecture-extra.md b/learners/software-architecture-extra.md index f478e03b1..1a5d9c82c 100644 --- a/learners/software-architecture-extra.md +++ b/learners/software-architecture-extra.md @@ -1,14 +1,16 @@ --- -title: Software Architecture +title: "Extra Content: Software Architecture" teaching: 15 exercises: 0 -questions: What should we consider when designing software? -objectives: Understand the components of multi-layer software architectures. -keypoints: Software architecture provides an answer to the question 'what components - will the software have and how will they cooperate?'. --- -## Software Architecture +::: questions +- What should we consider when designing software? +::: + +::: objectives +- Understand the components of multi-layer software architectures. +::: **Software architecture** provides an answer to the question "what components will the software have and how will they cooperate?". @@ -171,3 +173,7 @@ before displaying it to the user or passing it from the user to the Model. +::: keypoints: +- Software architecture provides an answer to the question 'what components + will the software have and how will they cooperate?'. +::: diff --git a/learners/vscode.md b/learners/vscode.md index 5f42a9b42..4f0a1a1fc 100644 --- a/learners/vscode.md +++ b/learners/vscode.md @@ -1,7 +1,15 @@ --- -title: Using Microsoft Visual Studio Code +title: "Extra Content: Using Microsoft Visual Studio Code" --- +::: objectives +- Use VS Code as an IDE of choice instead of PyCharm +::: + +::: questions +- How do we set up VS Code as our IDE of choice for this course? +::: + [Visual Studio Code (VS Code)](https://code.visualstudio.com/), not to be confused with [Visual Studio](https://visualstudio.microsoft.com/), is an Integrated Development Environment (IDE) by Microsoft. You can use it as your IDE for this course instead of PyCharm - bellow are some instructions to help you set up. @@ -193,6 +201,10 @@ the ordinary Run/Play icon, and a Run/Play icon with a bug. The latter allows you to run the tests in debug mode useful for obtaining further information as to why a failure has occurred - this will be covered in the main lesson material. +::: keypoints +- It is possible to switch to using VS Code for this course with a few tweaks +::: + [wsl]: https://learn.microsoft.com/en-us/windows/wsl/about [vscode-wsl-extension]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl [vscode-wsl-extension-launch-options]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl#commands diff --git a/links.md b/links.md new file mode 100644 index 000000000..2d8cd4b46 --- /dev/null +++ b/links.md @@ -0,0 +1,57 @@ +[best-practices]: http://journals.plos.org/plosbiology/article?id=10.1371/journal.pbio.1001745 +[cc-by-human]: https://creativecommons.org/licenses/by/4.0/ +[cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode +[ci]: http://communityin.org/ +[coc-reporting]: https://docs.carpentries.org/topic_folders/policies/incident-reporting.html +[coc]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html +[coderefinery-lessons]: https://coderefinery.org/lessons/ +[code-review]: https://en.wikipedia.org/wiki/Code_review +[concept-maps]: https://carpentries.github.io/instructor-training/05-memory/ +[contrib-covenant]: https://contributor-covenant.org/ +[cran-checkpoint]: https://cran.r-project.org/package=checkpoint +[cran-knitr]: https://cran.r-project.org/package=knitr +[cran-stringr]: https://cran.r-project.org/package=stringr +[dc-lessons]: http://www.datacarpentry.org/lessons/ +[email]: mailto:team@carpentries.org +[functional-programming]: https://en.wikipedia.org/wiki/Functional_programming +[gdpr]: https://ec.europa.eu/info/law/law-topic/data-protection/eu-data-protection-rules_en +[github-importer]: https://import2.github.com/ +[github-markdown]: https://guides.github.com/features/mastering-markdown/ +[github-actions]: https://docs.github.com/en/actions +[good-practices]: http://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510 +[importer]: https://github.com/new/import +[jekyll-collection]: https://jekyllrb.com/docs/collections/ +[jekyll-install]: https://jekyllrb.com/docs/installation/ +[jekyll-windows]: http://jekyll-windows.juthilo.com/ +[jekyll]: https://jekyllrb.com/ +[jupyter]: https://jupyter.org/ +[kramdown]: https://kramdown.gettalong.org/ +[lc-lessons]: https://librarycarpentry.org/lessons/ +[lesson-example]: https://carpentries.github.io/lesson-example/ +[mit-license]: https://opensource.org/licenses/mit-license.html +[morea]: https://morea-framework.github.io/ +[numfocus]: https://numfocus.org/ +[numpy]: http://www.numpy.org/ +[osi]: https://opensource.org +[pandas]: https://pandas.pydata.org/ +[pandoc]: https://pandoc.org/ +[paper-now]: https://github.com/PeerJ/paper-now +[pull-request]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests +[python-documentation]: https://docs.python.org/3/ +[python-gapminder]: https://swcarpentry.github.io/python-novice-gapminder/ +[pyyaml]: https://pypi.org/project/PyYAML/ +[r-markdown]: https://rmarkdown.rstudio.com/ +[rstudio]: https://www.rstudio.com/ +[ruby-install-guide]: https://www.ruby-lang.org/en/downloads/ +[ruby-installer]: https://rubyinstaller.org/ +[rubygems]: https://rubygems.org/pages/download/ +[scikit-learn]: https://github.com/scikit-learn/scikit-learn +[ssi]: https://software.ac.uk/ +[ssi-choosing-name]: https://software.ac.uk/resources/guides/choosing-project-and-product-names +[styles]: https://github.com/carpentries/styles/ +[swc-lessons]: https://software-carpentry.org/lessons/ +[swc-programming-with-python]: https://swcarpentry.github.io/python-novice-inflammation/ +[swc-releases]: https://github.com/swcarpentry/swc-releases +[training]: https://carpentries.github.io/instructor-training/ +[yaml]: http://yaml.org/ +[ssi-fair-lesson]: https://github.com/carpentries-incubator/fair-research-software