Merge pull request #12 from neuroinformatics-unit/collaborative-playg…

…round Collaborative playground
neuroinformatics-unit · Oct 9, 2023 · 11bc267 · 11bc267
2 parents cc729c6 + c6d816c
commit 11bc267
Show file tree

Hide file tree

Showing 6 changed files with 71 additions and 64 deletions.
diff --git 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 <a href="https://unsplash.com/@mparzuchowski?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Michał Parzuchowski</a> on <a href="https://unsplash.com/photos/yqD-v4fidt0?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a>](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/)
+{{< include slides/resources.qmd >}}
diff --git 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
@@ -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)
 :::
diff --git 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
diff --git a/slides/resources.qmd 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/)
diff --git 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,46 +29,35 @@
 
 [^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
 
 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")