From 5af29e0f2038d4dc8f12603dea42102d7981e37e Mon Sep 17 00:00:00 2001
From: Martin Geisler <martin.geisler@proton.ch>
Date: Sat, 31 Jan 2026 13:07:28 +0100
Subject: [PATCH 1/2] references: add explanatory commentary to solution

This commentary, written by Gemini, focuses on aspects of the solution that differ from the baseline languages (C/Java/Python), highlighting Rust-specific idioms and concepts.
---
 src/references/solution.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/references/solution.md b/src/references/solution.md
index f7b469b42b6d..d1fe2253436e 100644
--- a/src/references/solution.md
+++ b/src/references/solution.md
@@ -4,6 +4,18 @@
 {{#include exercise.rs:solution}}
 ```
 
+This solution highlights the difference between shared and mutable references:
+
+- **Shared References (`&`):** `magnitude` needs to read the vector components
+  but not modify them, so it takes a shared reference (`&[f64; 3]`).
+- **Mutable References (`&mut`):** `normalize` modifies the vector in place, so
+  it requires an exclusive mutable reference (`&mut [f64; 3]`).
+- **Dereferencing:** In the `normalize` loop, `item` is a `&mut f64`. To modify
+  the actual value, we must dereference it using `*item`.
+- **Iteration:** When we iterate over a reference to an array (like `vector`),
+  the iterator yields references to the elements. In `magnitude`, `coord` is
+  `&f64`. In `normalize`, `item` is `&mut f64`.
+
 <details>
 
 - Note that in `normalize` we were able to do `*item /= mag` to modify each

From 9c9d8ffd265dc19fc83b833dbe24ca9eb60d0efa Mon Sep 17 00:00:00 2001
From: Martin Geisler <martin@geisler.net>
Date: Sat, 14 Feb 2026 10:39:51 +0100
Subject: [PATCH 2/2] Refine solution commentary for experienced programmers

- Remove redundant or overly simplistic explanations.
- Focus on Rust-specific idioms and design choices.
- Clean up formatting and technical depth.
---
 src/references/solution.md | 37 +++++++++++++++++++------------------
 1 file changed, 19 insertions(+), 18 deletions(-)

diff --git a/src/references/solution.md b/src/references/solution.md
index d1fe2253436e..73215a485450 100644
--- a/src/references/solution.md
+++ b/src/references/solution.md
@@ -4,27 +4,28 @@
 {{#include exercise.rs:solution}}
 ```
 
-This solution highlights the difference between shared and mutable references:
+The solution demonstrates the fundamental distinction between shared and
+exclusive references:
 
-- **Shared References (`&`):** `magnitude` needs to read the vector components
-  but not modify them, so it takes a shared reference (`&[f64; 3]`).
-- **Mutable References (`&mut`):** `normalize` modifies the vector in place, so
-  it requires an exclusive mutable reference (`&mut [f64; 3]`).
-- **Dereferencing:** In the `normalize` loop, `item` is a `&mut f64`. To modify
-  the actual value, we must dereference it using `*item`.
-- **Iteration:** When we iterate over a reference to an array (like `vector`),
-  the iterator yields references to the elements. In `magnitude`, `coord` is
-  `&f64`. In `normalize`, `item` is `&mut f64`.
+- **Shared References (`&`):** Used in `magnitude` because the function only
+  reads the vector components.
+- **Exclusive References (`&mut`):** Required in `normalize` to modify the array
+  elements in place.
+- **Explicit Dereferencing:** Inside `normalize`, `item` is an `&mut f64`. We
+  use `*item` to access and modify the underlying value.
 
 <details>
 
-- Note that in `normalize` we were able to do `*item /= mag` to modify each
-  element. This is because we're iterating using a mutable reference to an
-  array, which causes the `for` loop to give mutable references to each element.
-
-- It is also possible to take slice references here, e.g.,
-  `fn
-  magnitude(vector: &[f64]) -> f64`. This makes the function more general,
-  at the cost of a runtime length check.
+- **Iterating over References:** Iterating over `&vector` or `&mut vector`
+  yields references to the elements. This is why `coord` is `&f64` and `item` is
+  `&mut f64`.
+- **Arrays vs. Slices:** The functions are defined using array references
+  (`&[f64; 3]`), which ensures the length is known at compile time. Using slices
+  (`&[f64]`) would make the functions more flexible but would introduce a
+  runtime length check or potential for panics if the slice has the wrong size.
+- **Method Call Ergonomics:** In `magnitude`, we can call `mag_squared.sqrt()`
+  directly. In `normalize`, we pass `vector` (an `&mut [f64; 3]`) to
+  `magnitude`, and Rust automatically downgrades the exclusive reference to a
+  shared reference to match the signature.
 
 </details>