From ee9c1e4f3f8fc3e4de1253d7495bc5e0e5359437 Mon Sep 17 00:00:00 2001 From: Aleksandra Nenadic Date: Fri, 28 Nov 2025 11:41:32 +0000 Subject: [PATCH 1/7] Tighten up wrap up. Move FAIR to extras. --- config.yaml | 1 + episodes/01-introduction.md | 10 ++ episodes/06-code-correctness.md | 26 ++-- episodes/07-software-documentation.md | 2 +- episodes/09-wrap-up.md | 137 +++---------------- learners/fair-software.md | 101 ++++++++++++++ learners/reproducible-research-discussion.md | 4 +- links.md | 2 + 8 files changed, 142 insertions(+), 141 deletions(-) create mode 100644 learners/fair-software.md diff --git a/config.yaml b/config.yaml index 55a3d3126..32ec8b3dd 100644 --- a/config.yaml +++ b/config.yaml @@ -74,6 +74,7 @@ episodes: learners: - installation-instructions.md - reproducible-research-discussion.md +- fair-software.md - test-suite-exercise.md - ci-for-testing.md - licensing.md diff --git a/episodes/01-introduction.md b/episodes/01-introduction.md index 8636da1a9..628ff6b49 100644 --- a/episodes/01-introduction.md +++ b/episodes/01-introduction.md @@ -92,6 +92,16 @@ Write your reflections in the shared collaborative document. :::::::::::::::::: +::: callout + +### FAIR software + +Some of the practices covered here also align with the [FAIR Research Software Principles][fair-principles-research-software] and are explored further in the [additional episode on FAIR software][fair-software-episode]. +However, FAIR is just one of several frameworks that can guide the development of high-quality research software. +What matters most is recognising how each of these individual practices—whether or not they come from FAIR—helps you produce software that is more reliable, maintainable, and useful to others. + +::: + ## Our research software project You are going to follow a fairly typical experience of a new researcher (e.g. a PhD student or a postdoc) joining a research group. diff --git a/episodes/06-code-correctness.md b/episodes/06-code-correctness.md index 32ba95bb0..d6c4fb7d2 100644 --- a/episodes/06-code-correctness.md +++ b/episodes/06-code-correctness.md @@ -1202,14 +1202,9 @@ to manage and run our tests using the `pytest` framework and how identify which parts of our code require additional testing using test coverage reports. -These skills reduce the probability that there will be a mistake in our -code and support reproducible research by giving us the confidence to -engage in open research practices. -Tests also document the intended behaviour of our code for other developers and mean that we can -experiment with changes to our code knowing that our tests will let us -know if we break any existing functionality. -In other words, software testing supports the [FAIR software principles][fair-principles-research-software] by making our code more **accessible** and -**reusable**. +These skills reduce the probability that there will be a mistake in our code and support reproducible research by giving us the confidence to engage in open research practices. +Tests also document the intended behaviour of our code for other developers and mean that we can experiment with changes to our code knowing that our tests will let us know if we break any existing functionality. +In other words, software testing supports building better software by making our code more **accessible** and **reusable**. :::::: spoiler @@ -1246,15 +1241,10 @@ the course. ::: keypoints -1. Code testing supports the FAIR principles by improving the - accessibility and re-usability of research code. -2. Unit testing is crucial as it ensures each functions works - correctly. -3. Using the `pytest` framework, you can write basic unit tests for - Python functions to verify their correctness. -4. Identifying and handling edge cases in unit tests is essential to - ensure your code performs correctly under a variety of conditions. -5. Test coverage can help you to identify parts of your code that - require additional testing. +1. Code testing supports building better software by improving the accessibility and re-usability of research code. +2. Unit testing is crucial as it ensures each functions works correctly. +3. Using the `pytest` framework, you can write basic unit tests for Python functions to verify their correctness. +4. Identifying and handling edge cases in unit tests is essential to ensure your code performs correctly under a variety of conditions. +5. Test coverage can help you to identify parts of your code that require additional testing. ::: diff --git a/episodes/07-software-documentation.md b/episodes/07-software-documentation.md index 755da8e97..ed731a627 100644 --- a/episodes/07-software-documentation.md +++ b/episodes/07-software-documentation.md @@ -61,7 +61,7 @@ However, like software testing, documenting our software help us produce **bette - Good documentation can help us return to a project seamlessly after time away - Documentation can facilitate collaborations by helping us onboard new project members quickly and more easily - Good documentation can save us time by answering frequently asked questions (FAQs) about our code for us -- Software documentation supports the [FAIR research software principles][fair-principles-research-software] by improving the re-usability of our code. +- Software documentation improves reusability of our code - Good documentation can make our software more understandable and reusable by others, and can bring us some citations and credit - How-to guides and tutorials ensure that users can install our software independently and make use of its basic features - Reference guides and background information can help developers understand our code sufficiently to modify/extend/repurpose it. diff --git a/episodes/09-wrap-up.md b/episodes/09-wrap-up.md index 242d018cb..57c96c70a 100644 --- a/episodes/09-wrap-up.md +++ b/episodes/09-wrap-up.md @@ -6,9 +6,7 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::: questions -- What are the FAIR principles? -- How can FAIR principles help us develop better research software? -- What are the wider research software development principles in the context of you team, peers and the world? +- What changes are you going to start implementing in your software development routine? :::::::::::::::::::::::::::::::::::::::::::::::: @@ -16,122 +14,33 @@ exercises: 0 After completing this episode, participants should be able to: -- Explain the FAIR research principles in the context of research software -- Explain why these principles are of value in the research community -- Reflect on the wider research software development principles and their relevance to research +- Reflect on the good research software development principles we covered in the course and their relevance in supporting reproducible research +- Start making changes to own software development practices to implement some of the principles we covered :::::::::::::::::::::::::::::::::::::::::::::::: -The good development practices taught in this lesson will help you build better research software. -The [final branch](https://github.com/carpentries-incubator/bbrs-software-project/tree/final) of the software project repository contains an improved version of the example code after good practices have been applied. -Some may require time and perseverance to implement and embed in your routine. -Others are small changes you can start practicing today. - -![Image by CCNULL, used under a CC-BY 2.0 licence](fig/plant-a-tree.jpg){alt="Chinese proverb 'The best time to plant a tree was 20 years ago. The second best time is now'"} - -## FAIR Research Software - -One framework that can help you evaluate the alignment of a piece of research software with best practices in reproducibility are the _FAIR Principles for Research Software_. -The practices taught here fall within this framework and it can be a good place to find out what else you can start doing to improve even further. - -### What is FAIR? - -FAIR stands for Findable, Accessible, Interoperable, and Reusable and comprises a set of principles designed to -increase the visibility and usefulness of your research to others. -The [FAIR data principles][fair-data-principles], first published in 2016, are widely known and applied today. -Similar [FAIR principles for software][fair-principles-research-software] have now been defined too. In general, they mean: - -- **Findable** - software and its associated metadata must be easy to discover by humans and machines. -- **Accessible** - in order to reuse software, the software and its metadata must be retrievable by standard protocols, free and legally usable. -- **Interoperable** - when interacting with other software it must be done by exchanging data and/or metadata through - standardised protocols and application programming interfaces (APIs). -- **Reusable** - software should be usable (can be executed) and reusable - (can be understood, modified, built upon, or incorporated into other software). - -Each of the above principles can be achieved by a number of practices listed below. -This is not an exact science, and by all means the list below is not exhaustive, -but any of the practices that you employ in your research software workflow will bring you -closer to the gold standard of fully reproducible research. +In this course, we explored some core practices that help researchers build high-quality, sustainable, and reusable software to support reproducible computational research. -#### Findable +We learned how to structure a project and track changes to it from the start, work with reproducible environments, write readable and well-organised code, test it for correctness, document it clearly, and share it for collaboration and reuse. +By putting these skills together, you now have a toolkit for developing research software that is more robust, more transparent, and easier for both you and others to use and maintain. -- Create a description of your software to make it discoverable by search engines and other search tools -- Use standards (such as [CodeMeta][codemeta]) to describe interoperable metadata for your software (see [Research Software Metadata Guidelines][rsmd-g1]) -- Place your software in a public software repository (and ideally register it in a [general-purpose or domain-specific software registry][awesome-rs-registries]) -- Use a unique and persistent identifier (DOI) for your software (e.g. by depositing your code on [Zenodo][zenodo]), - which is also useful for citations - note that depositing your data/code on GitHub and similar software repositories - may not be enough as they may change their open access model or disappear completely in the future, so archiving your code means it stands a better chance at being preserved - -#### Accessible - -- Make sure people can obtain get a copy of your software using standard communication protocols (e.g. HTTP(S), (S)FTP, etc.) -- The code and its description (metadata) has to be available even when the software is no longer actively developed (this includes earlier versions of the software) - -#### Interoperable - -- Use community-agreed standard formats for inputs and outputs of your software and its metadata -- Communicate with other software and tools via standard protocols and APIs - -#### Reusable - -- Document your software (including its functionality, how to install and run it) so it is both usable (can be executed) -and reusable (can be understood, modified, built upon, or incorporated into other software) -- Give a licence to your software clearly stating how it can be reused - -:::::: callout - -### FAIR is a process, not a perfect metric +As you continue your work, remember that small, consistent improvements in your practices make a big difference over time. +Some practices may require time and perseverance to implement and embed in your routine. +Others are small changes you can start practicing today. -FAIR is not a binary metric - there is no such thing as "FAIR or "not FAIR". +![Image by CCNULL, used under a CC-BY 2.0 licence](fig/plant-a-tree.jpg){alt="Chinese proverb 'The best time to plant a tree was 20 years ago. The second best time is now'"} -FAIR is not a perfect metric, nor does it provide a full and exhaustive software quality checklist - there are other good software quality practices not covered by FAIR. -Conversely, software may be FAIR but still not very good in terms of its functionality. +:::::: spoiler -FAIR is **not meant** to criticise or discredit work. +### Code state -FAIR refers to the specific **values** of and describes a set of **principles** to aid open and reproducible research that can be a helpful guide for researchers who want to improve their practices (by helping them see where they are on the **FAIR spectrum** and help them on a **journey** to make their software more FAIR). +The [final branch](https://github.com/carpentries-incubator/bbrs-software-project/tree/final) of the software project repository contains an improved version of the example code after good practices have been applied. :::::: -::::::::::::::::::::::::::::::::::::: checklist - -### Assessing the FAIRness of your Research Software - -Here are some questions to help you assess where on the FAIR spectrum your software is. - -1. **Findable** - - - If these files were emailed to you, or sent on a chat platform, or handed to you on a memory stick, how easy would it be to find them again in 6 months, or 3 years? - - If you asked your collaborator to give you the files again later on, how would you describe them? Do they have a clear name? - - If more data was added to the data set later, could you explain exactly which data you used in the original analysis? - -2. **Accessible** - - - If the person who gave you the files left your institution, how would you get access to the files again? - - Once you have the files, can you understand the code? Does it make sense to you? - - Do you need to log into anything to use this? Does it require purchase or subscription to a service, platform or tool? - -3. **Interoperable** +## Summary of tools and practices for building better research software - - Is it clear what kind of input data it can read and what kind of output data is produced? Will you be able to create the input files and read the output files with the tools your community generally uses? - - If you wanted to use this tool as part of a larger data processing pipeline, does it allow you to link it with other tools in standard ways such as an API or command-line interface? - -4. **Reusable** - - - Can you run the code on your platform/operating system (is there documentation that covers installation instructions)? What programs or libraries do you need to install to make it work (and which versions)? Are these commonly used tools in your field? - - Do you have explicit permission to use your collaborators code in your own research and do they expect credit of some form (paper authorship, citation or acknowledgement)? Are you allowed to edit, publish or share the files with others? - - Is the language used familiar to you and people in your research field? Can you read the variable names in the code and the column names in the data file and understand what they mean? - - Is the code written in a way that allows you to easily modify or extend it? Can you easily see what parameters to change to make it calculate a different statistic, or run on a different input file? - -:::::::::::::::::::::::::::::::::::::::::::::::: - -### FAIR Software is Better Software - -You may or may not find the FAIR Research Software Principles a helpful way of framing good practices. -The important thing is to focus on how **adopting these individual ways of working contributes to making your software better**. -Many of the practices taught here -- and advocated for in the FAIR framework -- will make your improve your life as a researcher and software developer. - -The table below provides a summary of some good practices for developing research software, together with different tools that can help with such practices and how they contribute to the the FAIR and other good software principles. +The table below provides a summary of some good practices for developing research software, together with different tools that can help with such practices and how they contribute to the the [FAIR][fair-software-episode] and other good software principles. | Practices | Tools | FAIR | Readable/Understandable | Correct/Reliable | Sustainable/Maintainable | |----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|------|-------------------------|-------------------|--------------------------| @@ -184,23 +93,11 @@ These principles can help us explore and reflect on our own work and guide us on ## Further reading -We recommend the following resources for some additional reading on FAIR Research Software: - -- ["Five recommendations for FAIR software"][5-fair-software-recommendations] -- ["10 easy things to make your research software FAIR"][10-easy-fair-things] -- ["Ten simple rules for training scientists to make better software"][10-rules-better-software] -- [Automating assessment of the FAIR Principles for Research Software (FAIR4RS)][automated-assessment-fairrs] -- [Short online courses][nesc-rs-support-courses] on various aspects of research software (including [FAIR research software][nesc-rs-support-course-fair] and data), by the NeSC Research Software Support -- [CodeRefinery][coderefinery] - training and e-Infrastructure for research software development -- A [self-assessment checklist for FAIR research software][fair-rs-checklist], by the Netherlands eScience Center and Australian Research Data Commons -- [Awesome Research Software Registries][awesome-rs-registries] - a list of research software registries (by country, organisation, domain and programming language) where research software can be registered to help promote its discovery - -Also check out [the full reference set for this course](learners/reference.md#litref). +Check out [the full reference set for the course](learners/reference.md#litref). :::::::::::::::::::::::::::::::::::::::: keypoints -- FAIR software and data is Findable, Accessible, Interoperable, Reusable and provide one framework for improving software and data practices in research. -- FAIR and other good research software principles, practices and tools support research and researchers by saving time, reducing barriers to discovery, and increasing impact of the research output. +- Following the building better software principles, practices and tools (whether or not they come from FAIR) supports computational research and researchers by saving time, reducing barriers to discovery, and increasing impact of the research output. - When developing software for your research, think about how it will help you and your team, your peers and domain/community and the world. :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/learners/fair-software.md b/learners/fair-software.md new file mode 100644 index 000000000..6982be159 --- /dev/null +++ b/learners/fair-software.md @@ -0,0 +1,101 @@ +## FAIR Research Software + +One framework that can help you evaluate the alignment of a piece of research software with best practices in reproducibility are the _FAIR Principles for Research Software_. +The practices taught here fall within this framework and it can be a good place to find out what else you can start doing to improve even further. + +### What is FAIR? + +FAIR stands for Findable, Accessible, Interoperable, and Reusable and comprises a set of principles designed to +increase the visibility and usefulness of your research to others. +The [FAIR data principles][fair-data-principles], first published in 2016, are widely known and applied today. +Similar [FAIR principles for software][fair-principles-research-software] have now been defined too. In general, they mean: + +- **Findable** - software and its associated metadata must be easy to discover by humans and machines. +- **Accessible** - in order to reuse software, the software and its metadata must be retrievable by standard protocols, free and legally usable. +- **Interoperable** - when interacting with other software it must be done by exchanging data and/or metadata through + standardised protocols and application programming interfaces (APIs). +- **Reusable** - software should be usable (can be executed) and reusable + (can be understood, modified, built upon, or incorporated into other software). + +Each of the above principles can be achieved by a number of practices listed below. +This is not an exact science, and by all means the list below is not exhaustive, +but any of the practices that you employ in your research software workflow will bring you +closer to the gold standard of fully reproducible research. + +#### Findable + +- Create a description of your software to make it discoverable by search engines and other search tools +- Use standards (such as [CodeMeta][codemeta]) to describe interoperable metadata for your software (see [Research Software Metadata Guidelines][rsmd-g1]) +- Place your software in a public software repository (and ideally register it in a [general-purpose or domain-specific software registry][awesome-rs-registries]) +- Use a unique and persistent identifier (DOI) for your software (e.g. by depositing your code on [Zenodo][zenodo]), + which is also useful for citations - note that depositing your data/code on GitHub and similar software repositories + may not be enough as they may change their open access model or disappear completely in the future, so archiving your code means it stands a better chance at being preserved + +#### Accessible + +- Make sure people can obtain get a copy of your software using standard communication protocols (e.g. HTTP(S), (S)FTP, etc.) +- The code and its description (metadata) has to be available even when the software is no longer actively developed (this includes earlier versions of the software) + +#### Interoperable + +- Use community-agreed standard formats for inputs and outputs of your software and its metadata +- Communicate with other software and tools via standard protocols and APIs + +#### Reusable + +- Document your software (including its functionality, how to install and run it) so it is both usable (can be executed) + and reusable (can be understood, modified, built upon, or incorporated into other software) +- Give a licence to your software clearly stating how it can be reused + +:::::: callout + +### FAIR is a process, not a perfect metric + +FAIR is not a binary metric - there is no such thing as "FAIR or "not FAIR". + +FAIR is not a perfect metric, nor does it provide a full and exhaustive software quality checklist - there are other good software quality practices not covered by FAIR. +Conversely, software may be FAIR but still not very good in terms of its functionality. + +FAIR is **not meant** to criticise or discredit work. + +FAIR refers to the specific **values** of and describes a set of **principles** to aid open and reproducible research that can be a helpful guide for researchers who want to improve their practices (by helping them see where they are on the **FAIR spectrum** and help them on a **journey** to make their software more FAIR). + +:::::: + +::::::::::::::::::::::::::::::::::::: checklist + +### Assessing the FAIRness of your Research Software + +Here are some questions to help you assess where on the FAIR spectrum your software is. + +1. **Findable** + +- If these files were emailed to you, or sent on a chat platform, or handed to you on a memory stick, how easy would it be to find them again in 6 months, or 3 years? +- If you asked your collaborator to give you the files again later on, how would you describe them? Do they have a clear name? +- If more data was added to the data set later, could you explain exactly which data you used in the original analysis? + +2. **Accessible** + +- If the person who gave you the files left your institution, how would you get access to the files again? +- Once you have the files, can you understand the code? Does it make sense to you? +- Do you need to log into anything to use this? Does it require purchase or subscription to a service, platform or tool? + +3. **Interoperable** + +- Is it clear what kind of input data it can read and what kind of output data is produced? Will you be able to create the input files and read the output files with the tools your community generally uses? +- If you wanted to use this tool as part of a larger data processing pipeline, does it allow you to link it with other tools in standard ways such as an API or command-line interface? + +4. **Reusable** + +- Can you run the code on your platform/operating system (is there documentation that covers installation instructions)? What programs or libraries do you need to install to make it work (and which versions)? Are these commonly used tools in your field? +- Do you have explicit permission to use your collaborators code in your own research and do they expect credit of some form (paper authorship, citation or acknowledgement)? Are you allowed to edit, publish or share the files with others? +- Is the language used familiar to you and people in your research field? Can you read the variable names in the code and the column names in the data file and understand what they mean? +- Is the code written in a way that allows you to easily modify or extend it? Can you easily see what parameters to change to make it calculate a different statistic, or run on a different input file? + +:::::::::::::::::::::::::::::::::::::::::::::::: + +### FAIR Software is Better Software + +You may or may not find the FAIR Research Software Principles a helpful way of framing good practices. +The important thing is to focus on **how adopting these individual ways of working contributes to making your software better**. +Many of the practices taught here -- and advocated for in the FAIR framework -- will make your improve your life as a researcher and software developer. \ No newline at end of file diff --git a/learners/reproducible-research-discussion.md b/learners/reproducible-research-discussion.md index 08bfb9e52..4524a9116 100644 --- a/learners/reproducible-research-discussion.md +++ b/learners/reproducible-research-discussion.md @@ -17,7 +17,7 @@ is fully transparent ([definition][wiki-reproducibility-def] from Wikipedia) * **Open research** - research that is openly accessible by others; concerned with making research more transparent, more collaborative, more wide-reaching, and more efficient ([definition][wiki-open-research-def] from Wikipedia) -* **FAIR** - an acronym that stands for Findable, Accessible, Interoperable, and Reusable +* **FAIR** - an acronym that stands for Findable, Accessible, Interoperable, and Reusable (check out our extra episode on [FAIR software][fair-software-episode]) * **Sustainable software development** - software development practice that takes into account longevity and maintainability of code (e.g. beyond the lifetime of the project), environmental impact, societal responsibility and ethics in our software practices. @@ -62,7 +62,7 @@ same research question and a qualitatively similar or identical answer is produc that are broadly applicable to different types of data or contexts. * For example, everything we drop - falls, therefore gravity exists. -![*The Turing Way project illustration of aspects of reproducible research by Scriberia, used under a CC-BY 4.0 licence, [DOI: 10.5281/zenodo.3332807][ttw-illustrations]*](https://raw.githubusercontent.com/the-turing-way/the-turing-way/refs/heads/main/book/website/figures/reproducible-definition-grid.svg){alt='Four cartoon images depicting two researchers at two machines which take in data and output the same landscape image in 4 different ways. These visually describe the four scenarios listed above.'} +![*The Turing Way project illustration of aspects of reproducible research by Scriberia, used under a CC-BY 4.0 licence, [DOI: 10.5281/zenodo.3332807][ttw-illustrations]*][ttw-reproducible-definition-grid]{alt='Four cartoon images depicting two researchers at two machines which take in data and output the same landscape image in 4 different ways. These visually describe the four scenarios listed above.'} In this course we mainly address the aspect of reproducibility - i.e. enabling others to run our code to obtain the same results. diff --git a/links.md b/links.md index 5a88f7d62..529043e82 100644 --- a/links.md +++ b/links.md @@ -62,6 +62,7 @@ any links that you are not going to use. [figshare]: https://figshare.com/ [forrt-resources]: https://forrt.org/resources/ [free-software]: https://www.gnu.org/philosophy/free-sw.en.html +[fair-software-episode]: ./fair-software.html [github]: https://github.com/ [github-copilot]: https://github.com/features/copilot @@ -147,6 +148,7 @@ any links that you are not going to use. [ttw-illustrations]: https://doi.org/10.5281/zenodo.3332807 [ttw-reproducibility-def]: https://the-turing-way.netlify.app/reproducible-research/overview/overview-definitions [turing-way-citation]: https://book.the-turing-way.org/communication/citable/citable-cff.html +[ttw-reproducible-definition-grid]: https://raw.githubusercontent.com/the-turing-way/the-turing-way/refs/heads/main/book/figures/reproducible-definition-grid.svg [wiki-open-research-def]: https://en.wikipedia.org/wiki/Open_research [wiki-reproducibility-def]: https://en.wikipedia.org/wiki/Reproducibility From a9aa6216e7cd6d5efb6be7e98a9225730f3825ad Mon Sep 17 00:00:00 2001 From: Aleksandra Nenadic Date: Fri, 5 Dec 2025 10:26:08 +0000 Subject: [PATCH 2/7] Update episodes/06-code-correctness.md Co-authored-by: Toby Hodges --- episodes/06-code-correctness.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/episodes/06-code-correctness.md b/episodes/06-code-correctness.md index d6c4fb7d2..9f6658170 100644 --- a/episodes/06-code-correctness.md +++ b/episodes/06-code-correctness.md @@ -1203,7 +1203,7 @@ which parts of our code require additional testing using test coverage reports. These skills reduce the probability that there will be a mistake in our code and support reproducible research by giving us the confidence to engage in open research practices. -Tests also document the intended behaviour of our code for other developers and mean that we can experiment with changes to our code knowing that our tests will let us know if we break any existing functionality. +Tests also document the intended behaviour of our code for other developers and allow us to safely experiment with changes to our code, knowing that our tests will tell us if we break any existing functionality. In other words, software testing supports building better software by making our code more **accessible** and **reusable**. :::::: spoiler From 0a208b2be4bca5ad39fdbd32f31bb862ed958ad0 Mon Sep 17 00:00:00 2001 From: Aleksandra Nenadic Date: Fri, 5 Dec 2025 10:26:19 +0000 Subject: [PATCH 3/7] Update episodes/06-code-correctness.md Co-authored-by: Toby Hodges --- episodes/06-code-correctness.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/episodes/06-code-correctness.md b/episodes/06-code-correctness.md index 9f6658170..4f76b4b32 100644 --- a/episodes/06-code-correctness.md +++ b/episodes/06-code-correctness.md @@ -1242,7 +1242,7 @@ the course. ::: keypoints 1. Code testing supports building better software by improving the accessibility and re-usability of research code. -2. Unit testing is crucial as it ensures each functions works correctly. +2. Unit testing is crucial as it ensures each function works correctly. 3. Using the `pytest` framework, you can write basic unit tests for Python functions to verify their correctness. 4. Identifying and handling edge cases in unit tests is essential to ensure your code performs correctly under a variety of conditions. 5. Test coverage can help you to identify parts of your code that require additional testing. From c69a5c7dc1af4307c7660d301964e41fba3aacfe Mon Sep 17 00:00:00 2001 From: Aleksandra Nenadic Date: Fri, 5 Dec 2025 10:26:32 +0000 Subject: [PATCH 4/7] Update episodes/09-wrap-up.md Co-authored-by: Toby Hodges --- episodes/09-wrap-up.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/episodes/09-wrap-up.md b/episodes/09-wrap-up.md index 57c96c70a..785295e53 100644 --- a/episodes/09-wrap-up.md +++ b/episodes/09-wrap-up.md @@ -15,7 +15,7 @@ exercises: 0 After completing this episode, participants should be able to: - Reflect on the good research software development principles we covered in the course and their relevance in supporting reproducible research -- Start making changes to own software development practices to implement some of the principles we covered +- Start making changes to their own software development practices to implement some of the principles we covered :::::::::::::::::::::::::::::::::::::::::::::::: From ac79f0a5c9554f5c500eecfd5156bbcecd0ac593 Mon Sep 17 00:00:00 2001 From: Aleksandra Nenadic Date: Fri, 5 Dec 2025 10:26:42 +0000 Subject: [PATCH 5/7] Update episodes/09-wrap-up.md Co-authored-by: Toby Hodges --- episodes/09-wrap-up.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/episodes/09-wrap-up.md b/episodes/09-wrap-up.md index 785295e53..f047d21d4 100644 --- a/episodes/09-wrap-up.md +++ b/episodes/09-wrap-up.md @@ -21,7 +21,7 @@ After completing this episode, participants should be able to: In this course, we explored some core practices that help researchers build high-quality, sustainable, and reusable software to support reproducible computational research. -We learned how to structure a project and track changes to it from the start, work with reproducible environments, write readable and well-organised code, test it for correctness, document it clearly, and share it for collaboration and reuse. +You learned how to structure a project and track changes to it from the start, work with reproducible environments, write readable and well-organised code, test it for correctness, document it clearly, and share it for collaboration and reuse. By putting these skills together, you now have a toolkit for developing research software that is more robust, more transparent, and easier for both you and others to use and maintain. As you continue your work, remember that small, consistent improvements in your practices make a big difference over time. From b00b638cf8eac9cc3c1b6d7952c5400cc3ab86e2 Mon Sep 17 00:00:00 2001 From: Aleksandra Nenadic Date: Fri, 5 Dec 2025 10:26:51 +0000 Subject: [PATCH 6/7] Update episodes/09-wrap-up.md Co-authored-by: Toby Hodges --- episodes/09-wrap-up.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/episodes/09-wrap-up.md b/episodes/09-wrap-up.md index f047d21d4..37d48dc17 100644 --- a/episodes/09-wrap-up.md +++ b/episodes/09-wrap-up.md @@ -25,7 +25,7 @@ You learned how to structure a project and track changes to it from the start, w By putting these skills together, you now have a toolkit for developing research software that is more robust, more transparent, and easier for both you and others to use and maintain. As you continue your work, remember that small, consistent improvements in your practices make a big difference over time. -Some practices may require time and perseverance to implement and embed in your routine. +Some practices may require time and persistence to implement and embed in your routine. Others are small changes you can start practicing today. ![Image by CCNULL, used under a CC-BY 2.0 licence](fig/plant-a-tree.jpg){alt="Chinese proverb 'The best time to plant a tree was 20 years ago. The second best time is now'"} From 0aa2b3eea394fcac1d46db653f09877cd869c4fd Mon Sep 17 00:00:00 2001 From: Aleksandra Nenadic Date: Fri, 5 Dec 2025 10:27:06 +0000 Subject: [PATCH 7/7] Update episodes/09-wrap-up.md Co-authored-by: Toby Hodges --- episodes/09-wrap-up.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/episodes/09-wrap-up.md b/episodes/09-wrap-up.md index 37d48dc17..1ef36d671 100644 --- a/episodes/09-wrap-up.md +++ b/episodes/09-wrap-up.md @@ -97,7 +97,7 @@ Check out [the full reference set for the course](learners/reference.md#litref). :::::::::::::::::::::::::::::::::::::::: keypoints -- Following the building better software principles, practices and tools (whether or not they come from FAIR) supports computational research and researchers by saving time, reducing barriers to discovery, and increasing impact of the research output. +- The principles, practices and tools promoted in this course (including the FAIR principles for research software) support computational research and researchers by saving time, reducing barriers to discovery, and increasing impact of the research output. - When developing software for your research, think about how it will help you and your team, your peers and domain/community and the world. ::::::::::::::::::::::::::::::::::::::::::::::::::