📚 Formatting & Linting: add linting sections

Author: mbercx

docs/formatting.md

@@ -1,27 +1,26 @@
-# Formatting
+# Formatting & Linting
 
 ## What
 
-Code formatting refers to the consistent styling of your code - how it looks visually.
+**Code formatting** refers to the consistent styling of your code - how it looks visually.
 This includes indentation, spacing, line length, quote styles, and other stylistic choices that don't affect how the code runs but impact how it reads.
 
-A code formatter automatically reformats your code to follow a consistent style.
-Popular Python formatters include:
-
-- **black**: An opinionated formatter that enforces a strict style with minimal configuration.
-- **ruff**: A fast formatter that can also perform linting (checking for code quality issues).
+**Linting** checks your code for potential bugs, code smells, and programming errors.
+It catches issues like unused variables, undefined names, or overly complex code before they cause problems.
 
 ## Why
 
-Consistent formatting serves several important purposes:
+**Formatting** helps you focus on logic rather than style:
 
-**Focus on logic, not style**: With automatic formatting, you don't waste time or mental energy deciding where to put spaces, how to break lines, or arguing about style preferences during code reviews.
+- **Save time and energy**: No more deciding where to put spaces or how to break lines
+- **Improved readability**: Consistent code is easier to read and understand
+- **Better collaboration**: Everyone's code looks the same, so git diffs show real changes instead of whitespace adjustments
 
-**Improved readability**: Consistent code is easier to read and understand.
-When all code follows the same patterns, you can focus on what the code does rather than getting distracted by inconsistent styling.
+**Linting** catches bugs before they happen:
 
-**Better collaboration**: When everyone's code looks the same, it's easier to work together.
-Code reviews focus on functionality rather than style preferences, and git diffs show real changes instead of whitespace adjustments.
+- **Early bug detection**: Find issues like unused variables or undefined names before running your code
+- **Code quality**: Identify overly complex code, missing error handling, or potential performance issues
+- **Learn best practices**: Linters teach you Python conventions and common pitfalls to avoid
 
 !!!example "Real-world scenario"
 
@@ -37,7 +36,7 @@ Code reviews focus on functionality rather than style preferences, and git diffs
 
 ## How
 
-We'll use `ruff` as our formatter.
+We'll use `ruff` as our tool of choice.
 It's fast, modern, and can handle both formatting (using `black` under the hood) and linting.
 Let's install `ruff` in our environment:
 
@@ -46,13 +45,13 @@ pip install ruff
 ```
 
 Let's see `ruff` in action!
-First, create a poorly formatted Python file to demonstrate the formatter.
-
-Copy this messy code into a new file `src/dev_tutorial/messy.py`:
+Have a look at the file `src/dev_tutorial/messy.py`:
 
-```python
+```python {.no-copy}
+# src/dev_tutorial/messy.py
 def calculate_statistics(data,include_median=True):
     """Calculate statistics for a list of numbers."""
+    debug_mode=True
     if len(data)==0:
         return None
 
@@ -77,14 +76,112 @@ This code has several formatting issues:
 Now run the formatter:
 
 ```
-ruff format
+ruff format src/dev_tutorial/messy_code.py
 ```
 
-You should see output like:
-
 ```console {.no-copy}
 1 file reformatted
 ```
 
 Open `src/dev_tutorial/messy.py` again and check how the code has changed.
-`ruff` has automatically fixed all the formatting issues.
+`ruff` has automatically fixed all the formatting issues:
+
+```python
+def calculate_statistics(data, include_median=True):
+    """Calculate statistics for a list of numbers."""
+    debug_mode = True
+    if len(data) == 0:
+        return None
+
+    mean = sum(data) / len(data)
+    result = {"mean": mean, "min": min(data), "max": max(data)}
+
+    if include_median:
+        sorted_data = sorted(data)
+        n = len(sorted_data)
+        median = (
+            sorted_data[n // 2]
+            if n % 2 != 0
+            else (sorted_data[n // 2 - 1] + sorted_data[n // 2]) / 2
+        )
+        result["median"] = median
+
+    return result
+```
+
+Much better!
+But we still haven't checked the code for quality issues.
+Let's run the linter:
+
+```
+ruff check src/dev_tutorial/messy_code.py
+```
+
+```console {.no-copy}
+F841 Local variable `debug_mode` is assigned to but never used
+ --> src/dev_tutorial/messy_code.py:3:5
+  |
+1 | def calculate_statistics(data, include_median=True):
+2 |     """Calculate statistics for a list of numbers."""
+3 |     debug_mode = True
+  |     ^^^^^^^^^^
+4 |     if len(data) == 0:
+5 |         return None
+  |
+help: Remove assignment to unused variable `debug_mode`
+
+Found 1 error.
+No fixes available (1 hidden fix can be enabled with the `--unsafe-fixes` option).
+```
+
+The linter found an issue with our code!
+To understand the problem, run:
+
+```
+ruff rule F841
+```
+
+Now fix the issue by removing the unused `debug_mode` variable
+After making these changes manually, run both commands again to verify everything is clean:
+
+```
+ruff format && ruff check
+```
+
+### Automating with pre-commit
+
+Instead of remembering to run `ruff format` and `ruff check` before every commit, you can use `pre-commit` to automatically run these checks.
+
+`pre-commit` is a framework that manages git hooks - scripts that run automatically before you commit code.
+
+First, install pre-commit:
+
+```
+pip install pre-commit
+```
+
+The project already has a `.pre-commit-config.yaml` file that configures which checks to run (have a look!).
+To install the git hooks, run:
+
+```
+pre-commit install
+```
+
+Now, every time you try to commit code, `pre-commit` will automatically:
+
+1. Run `ruff format` to format your code
+2. Run `ruff check` to lint your code
+3. If any issues are found, the commit will be blocked until you fix them
+
+You can also run the checks manually without committing:
+
+```
+pre-commit run -a
+```
+
+This ensures your code is always formatted and linted before it enters version control!
+
+!!! tip "Give it a try!"
+
+    Try to make some changes to one of the modules, and run `git commit`.
+    Both the linter and formatter should run automatically.

docs/index.md

@@ -14,7 +14,7 @@ Topics that will be covered:
 - [Packages](packages.md)
 - [Writing documentation](documentation.md)
 - [Testing with `pytest`](tests.md)
-- Formatting/linting your code with Ruff
+- [Formatting/linting your code with Ruff](formatting.md)
 - Continuous Integration (CI)
 - Publishing your code on the PyPI (CD)
 
@@ -27,7 +27,3 @@ You won't need any advanced Python concepts, but understanding basic syntax will
     **Don't worry in case you don't understand everything right away!**
     All of this is very intimidating at first, I know, I've been there.
     It took me a long time to learn how to use these tools, and I'm still learning more every day.
-
-!!! note
-
-    The material presented here is mostly based on my experience, but has also been inspired by [this excellent guide](https://learn.scientific-python.org/development/) from the [Scientific Python project](https://github.com/scientific-python). 

template/src/{{ package_name.lower().replace('-', '_') }}/functions.py

@@ -1,5 +1,6 @@
 """Example functions."""
 
+
 def add(a, b):
     return a + b
 
@@ -10,4 +11,3 @@ def sum_and_multiply(integer_list, factor):
 
 def multiply(integer_list, factor):
     return [value * factor for value in integer_list]
-    

template/src/{{ package_name.lower().replace('-', '_') }}/messy_code.py

@@ -0,0 +1,16 @@
+def calculate_statistics(data,include_median=True):
+    """Calculate statistics for a list of numbers."""
+    debug_mode=True
+    if len(data)==0:
+        return None
+
+    mean=sum(data)/len(data)
+    result={'mean':mean,'min':min(data),'max':max(data)}
+
+    if include_median:
+        sorted_data=sorted(data)
+        n=len(sorted_data)
+        median=sorted_data[n//2] if n%2!=0 else (sorted_data[n//2-1]+sorted_data[n//2])/2
+        result['median']=median
+
+    return result