diff --git a/index.qmd b/index.qmd index 1325a1f..0656ef0 100644 --- a/index.qmd +++ b/index.qmd @@ -42,6 +42,8 @@ format: margin-left: 0 embed-resources: true page-layout: full +exercises: + org-repo: "rse-best-practices-course-2023/rse-best-practices-playground" --- ## [Neuroinformatics unit](https://neuroinformatics.dev/people.html){preview-link="true"} @@ -79,6 +81,7 @@ Remark about RSE movement and its importance to research. ::: {.column width="50%"} * a GitHub account * followed setup instructions +* open these slides on your laptop ::: :::: @@ -144,6 +147,7 @@ pip install my_awesome_package ::: {.column width="50%"} * make a mess * break things +* be active * embrace the chaos * have fun ::: @@ -170,38 +174,5 @@ pip install my_awesome_package * evaluating and improving the quality of code 🤔 (code smells, refactoring, DRY) * creating a python package 📦 (cookiecutter, pypi) -## Documentation resources -## Testing resources - -* [Pytest docs](https://docs.pytest.org/en/7.3.x/) - -## Code review and issue tracking resources -:::: {.columns} - -::: {.column width="50%" style="font-size: 0.5em;"} -![Photo by Michał Parzuchowski on Unsplash](img/michal-parzuchowski-yqD-v4fidt0-unsplash.jpg){height=400} -::: - -::: {.column width="50%"} -* [Step-by-step guide](https://blog.ossph.org/a-beginners-guide-to-contributing-to-open-source-projects/) -* Advice on how to do code review: - * as [an author](https://mtlynch.io/code-review-love/) - * as [a reviewer](https://mtlynch.io/human-code-reviews-1/) -* The Zeigarnik effect: Why creating issues [helps you switch off](https://todoist.com/inspiration/zeigarnik-effect-comic) -::: -:::: - -## RSE Community - -* join the community! - * [SWC slack `#software-skills`](swc-neuro.slack.com) - * [UCL Research Programming Hub](https://www.ucl.ac.uk/advanced-research-computing/community/ucl-research-programming-hub) - * [Research Software London](https://rslondon.ac.uk/) - * [Research Software Engineering societies](https://society-rse.org/international-rse-organisations/) - -### More context about Research Software Engineering - -* [The four pillare of RSE](https://ieeexplore.ieee.org/document/8994167) -* [The Software Sustainability Institute](https://www.software.ac.uk/) -* [The hidden REF – Celebrating all research outputs](https://hidden-ref.org/) \ No newline at end of file +{{< include slides/resources.qmd >}} \ No newline at end of file diff --git a/slides/collaborate.qmd b/slides/collaborate.qmd index 25fff3c..e7d6353 100644 --- a/slides/collaborate.qmd +++ b/slides/collaborate.qmd @@ -27,7 +27,7 @@ ::: :::: -## [The development cycle](https://github.com/neuroinformatics-unit/rse-best-practices-playground){preview-link="true" style="text-align: center"} +## [The development cycle](https://github.com/{{< meta exercises.org-repo >}}){preview-link="true" style="text-align: center"} :::: {.columns} @@ -43,10 +43,10 @@ ::: :::: -## Exercise: Have you set up [your playground?](https://github.com/neuroinformatics-unit/rse-best-practices-playground-trial/issues/1){preview-link="true" style="text-align: center"} +## Exercise: Have you set up [your playground?](https://github.com/{{< meta exercises.org-repo >}}/issues/1){preview-link="true" style="text-align: center"} -## What makes research code good? +## What makes (research) code good? {{< include slides/mentimeter.qmd >}} diff --git a/slides/documentation.qmd b/slides/documentation.qmd index 87cb57d..a55b732 100644 --- a/slides/documentation.qmd +++ b/slides/documentation.qmd @@ -48,7 +48,7 @@ def get_named_colors_mapping(): Docstrings (should) follow an [agreed convention](https://peps.python.org/pep-0257/){preview-link="true"} -## A first task: [writing a docstring](https://github.com/neuroinformatics-unit/rse-best-practices-playground) +## A first task: [writing a docstring](https://github.com/{{< meta exercises.org-repo >}}) ``` {.python} def calculate_fastest_time(time_list): @@ -60,5 +60,5 @@ def calculate_fastest_time(time_list): ``` ::: {style="text-align: center; margin-top: 1em"} -[Exercise: write a docstring for a function in `times.py`](https://packaging.python.org/en/latest/tutorials/packaging-projects/) +[Exercise: write a docstring for a function in `times.py`](https://github.com/{{< meta exercises.org-repo >}}/issues/2) ::: \ No newline at end of file diff --git a/slides/refactoring.qmd b/slides/refactoring.qmd index bf6750d..6ff71e1 100644 --- a/slides/refactoring.qmd +++ b/slides/refactoring.qmd @@ -1 +1,7 @@ # Code Quality + +## Code smells + +> A code smell is a surface indication that usually corresponds to a deeper problem in the system. + +- Martin Fowler \ No newline at end of file diff --git a/slides/resources.qmd b/slides/resources.qmd new file mode 100644 index 0000000..9893c8d --- /dev/null +++ b/slides/resources.qmd @@ -0,0 +1,40 @@ +# Resources + +## Documentation resources + +## Testing resources + +* [Pytest docs](https://docs.pytest.org/en/7.3.x/) + +## Refactoring resources + +* [31 code smells](https://pragmaticways.com/31-code-smells-you-must-know/) + + +## Packaging resources + +* [NIU cookiecutter](https://github.com/neuroinformatics-unit/python-cookiecutter) +* [Python packaging tutorial](https://packaging.python.org/en/latest/tutorials/packaging-projects/) +* [Python wheels walkthrough](https://youtu.be/FpIJ7T1Gpjo?feature=shared&t=1638) + +## Code review and issue tracking resources + +* [Step-by-step guide](https://blog.ossph.org/a-beginners-guide-to-contributing-to-open-source-projects/) +* Advice on how to do code review: + * as [an author](https://mtlynch.io/code-review-love/) + * as [a reviewer](https://mtlynch.io/human-code-reviews-1/) +* The Zeigarnik effect: Why creating issues [helps you switch off](https://todoist.com/inspiration/zeigarnik-effect-comic) + +## RSE Community + +* join the community! + * [SWC slack `#software-skills`](swc-neuro.slack.com) + * [UCL Research Programming Hub](https://www.ucl.ac.uk/advanced-research-computing/community/ucl-research-programming-hub) + * [Research Software London](https://rslondon.ac.uk/) + * [Research Software Engineering societies](https://society-rse.org/international-rse-organisations/) + +### More context about Research Software Engineering + +* [The four pillare of RSE](https://ieeexplore.ieee.org/document/8994167) +* [The Software Sustainability Institute](https://www.software.ac.uk/) +* [The hidden REF – Celebrating all research outputs](https://hidden-ref.org/) \ No newline at end of file diff --git a/slides/testing.qmd b/slides/testing.qmd index 34d1fe2..e4476c4 100644 --- a/slides/testing.qmd +++ b/slides/testing.qmd @@ -3,7 +3,7 @@ ## Why should you test * to find (current and future) bugs earlier and more quickly (before you publish your results, ideally!) -* to have confidence in your code changes +* to have confidence in your current and future code * (to document how you expect your code to behave) ## Why should you test your research code? @@ -29,36 +29,25 @@ [^fire-lab]: [https://software.ac.uk/news/software-horror-stories-fire-lab](https://software.ac.uk/news/software-horror-stories-fire-lab) -## What things should we sanity check about the `compute_overlap` function? +## What things should we sanity check about the `calculate_fastest_time` function? ```{.python} -def time_range( - start_time, end_time, number_of_intervals=1, gap_between_intervals_s=0 -): - """ - Example: - >>> time_range("2010-01-12 10:00:00", "2010-01-12 12:00:00", 2, 60) - [('2010-01-12 10:00:00', '2010-01-12 12:00:00')] - """ - ... - -def compute_overlap_time(range1, range2): - overlap_time = [] - for start1, end1 in range1: - for start2, end2 in range2: - low = max(start1, start2) - high = min(end1, end2) - overlap_time.append((low, high)) - return overlap_time +def calculate_fastest_time(time_list): + fastest_time = time_list[0] + for time in time_list: + if time > fastest_time: + fastest_time = time + return fastest_time ``` -## What things should we sanity check about this code? +## What things should we sanity check about the `calculate_fastest_time` function? {{< include slides/mentimeter.qmd >}} ## Demo: write some sanity checks Switch to VS Code + {{< include slides/mentimeter.qmd >}} ## Testing with pytest @@ -66,9 +55,9 @@ Switch to VS Code A neater way to run sanity checks ```{.python} -import compute_overlap_time +import .calculate_fastest_time -def test_given_input(): +def test_fastest_time_in_a_specific_case(): ... result = ... expected = ... @@ -77,7 +66,7 @@ def test_given_input(): ## Exercise: convert a sanity check into a test -[Testing exercise](https://github.com/neuroinformatics-unit/rse-good-practice-playground/issues/2) +[Testing exercise](https://github.com/{{< meta exercises.org-repo >}}/issues/2) ## How to think about what to test @@ -95,10 +84,11 @@ Try to cover all "edge" cases[^2]: what happens if ...? [^2]: [A Beginner’s Guide to Testing: Error Handling Edge Cases](https://www.freecodecamp.org/news/a-beginners-guide-to-testing-implement-these-quick-checks-to-test-your-code-d50027ad5eed/) -## How to think about what to test +## How to think about what to test {.smaller} What we've called sanity checks are referred to as "test cases". For example, what happens/should happen when you call...? + * `calculate_fastest_time("this is a string")` ("zero") * `calculate_fastest_time([1.0])` ("one") * `calculate_fastest_time([1.0]); calculate_fastest_time([2.0])` ("two")