lessons 03: fix comments, add questions in lesson, add example in Python (#98)

Co-authored-by: Wojciech Przytuła <[email protected]>

Author: tonowak

content/lessons/03_data_types/data_types.rs

@@ -1,5 +1,5 @@
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
-struct Position(i32, i32); // tuple struct
+struct Position(i32, i32); // This is a "tuple struct".
 
 // Could Hero derive the Copy trait?
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -10,9 +10,10 @@ struct Hero {
     position: Position,
 }
 
-// we can add methods to structs using the 'impl' keyword
+// We can add methods to structs using the 'impl' keyword.
 impl Hero {
-    // static method (in Rust nomenclature: "associated function")
+    // Static method (in Rust nomenclature: "associated function").
+    // It can then be called as follows: `Hero::new(String::from("Ferris"))`.
     fn new(name: String) -> Hero {
         Hero {
             name,
@@ -23,38 +24,43 @@ impl Hero {
     }
 }
 
-// multiple impl blocks are possible for one struct
+// We can have multiple `impl` blocks for one struct.
 impl Hero {
-    // instance method, first argument (self) is the calling instance
+    // Instance method. The first argument (self) is the calling instance,
+    // just like `self` in Python and `this` in C++.
     fn distance(&self, pos: Position) -> u32 {
-        // shorthand to: `self: &Self`
-        // field `i` of a tuple or a tuple struct can be accessed through 'tuple.i'
+        // For convenience, we don't have to type the argument as `self: &Self`.
+        // The i-th field of a tuple or a tuple struct can be accessed through 'tuple.i'.
+        // Do not abuse this syntax, though; it's often cleaner to perform
+        // pattern matching to decompose the tuple.
         (pos.0 - self.position.0).unsigned_abs() + (pos.1 - self.position.1).unsigned_abs()
     }
 
-    // mutable borrow of self allows to change instance fields
+    // Mutable borrow of self allows to change instance fields.
     fn level_up(&mut self) {
-        // shorthand to: `self: &mut Self`
+        // Again, we don't have to type the argument as `self: &mut Self`.
         self.experience = 0;
         self.level += 1;
     }
 
-    // 'self' is not borrowed here and will be moved into the method
+    // 'self' is not borrowed here and will be moved into the method.
     fn die(self) {
-        // shorthand to: `self: Self`
         println!(
             "Here lies {}, a hero who reached level {}. RIP.",
             self.name, self.level
         );
+        // The `self: Self` is now dropped.
     }
 }
 
 fn main() {
     // Calling associated functions requires scope (`::`) operator.
     let mut hero: Hero = Hero::new(String::from("Ferris"));
-    hero.level_up(); // 'self' is always passed implicitly
+    hero.level_up(); // 'self' is always passed implicitly as the first argument.
 
-    // fields other than 'name' will be the same as in 'hero'
+    // Thanks to `..hero`, fields other than 'name' will be the same as in 'hero'.
+    // In general, they are moved. Here, they are copied, because all missing fields
+    // implement the `Copy` trait.
     let steve = Hero {
         name: String::from("Steve The Normal Guy"),
         ..hero
@@ -64,25 +70,26 @@ fn main() {
 
     let mut twin = hero.clone();
 
-    // we can compare Hero objects because it derives the PartialEq trait
+    // We can compare `Hero` objects because it derives the `PartialEq` trait.
     assert_eq!(hero, twin);
     twin.level_up();
     assert_ne!(hero, twin);
     hero.level_up();
     assert_eq!(hero, twin);
 
-    // we can print out a the struct's debug string with '{:?}'
+    // We can print out the struct's debug string
+    // (which is implemented thanks to `Debug` trait) with '{:?}'.
     println!("print to stdout: {:?}", hero);
 
-    hero.die(); // 'hero' is not usable after this invocation, see the method's definiton
+    hero.die(); // 'hero' is not usable after this invocation, see the method's definiton.
 
-    // the dbg! macro prints debug strings to stderr along with file and line number
-    // dbg! takes its arguments by value, so better borrow them not to have them
-    // moved into dbg! and consumed.
+    // The `dbg!` macro prints debug strings to stderr along with file and line number.
+    // `dbg!` takes its arguments by value, so it's better to borrow them to not have them
+    // moved into `dbg!` and consumed.
     dbg!("print to stderr: {}", &twin);
 
     let pos = Position(42, 0);
-    let dist = steve.distance(pos); // no clone here as Position derives the Copy trait
+    let dist = steve.distance(pos); // No clone here as `Position` derives the `Copy` trait.
     println!("{:?}", pos);
     assert_eq!(dist, 42);
 }

content/lessons/03_data_types/index.md

@@ -1,21 +1,22 @@
 +++
 title = "Data Types"
-date = 2029-01-01
+date = 2025-10-15
 weight = 1
 [extra]
-lesson_date = 2029-01-01
+lesson_date = 2025-10-16
 +++
 
 ## Aggregating data
 
-Below is a compact overview of Rust's structs
+Below is a compact overview of Rust's structs.
 
 {{ include_code_sample(path="lessons/03_data_types/data_types.rs", language="rust") }}
 
 ## Enums
 
 It is often the case that we want to define a variable that can only take
-a certain set of values and the values are known up front. In C you can use an `enum` for this.
+a certain set of values and the values are known up front.
+Just like the below code shows, in C you can use an `enum` for this.
 
 {{ include_code_sample(path="lessons/03_data_types/enums.c", language="c") }}
 
@@ -38,9 +39,14 @@ C++ introduces enum classes which are type-safe. Legacy enums are also somewhat
       |                               int
 ```
 
+Even though in this case we got an error, we can still write code that somehow casts the integer to the enum.
+
+## Algebraic data types
+
 Some programming languages (especially functional ones) allow programmers to define
 enums which carry additional information. Such types are usually called `tagged unions`
-or `algebraic data types`.
+or `algebraic data types`. This name can be new to you, but there's a chance that you
+already used it (or something similar). It's pretty easy to understand it.
 
 In C++ we can use `union` with an `enum` tag to define it:
 
@@ -52,6 +58,10 @@ You can read more about it [here](https://en.cppreference.com/w/cpp/utility/vari
 Java has a more or less analogous feature called `sealed classes`
 since [version 17](https://docs.oracle.com/en/java/javase/17/language/sealed-classes-and-interfaces.html.).
 
+In Python, this is quite clean starting from Python 3.10.
+
+{{ include_code_sample(path="lessons/03_data_types/variant.py", language="py") }}
+
 ## Enums in Rust
 
 Let's see how they are defined in Rust.
@@ -82,6 +92,14 @@ the solution to the billion dollar mistake!
 
 {{ include_code_sample(path="lessons/03_data_types/option.rs", language="rust") }}
 
+## To discuss during class
+
+- Why `enum` is considered a core feature of the language?
+- How Rust `enum`s could save us during standard project refactors/library usages, which wouldn't be as safe in some other languages?
+- People find Rust `enum`s convenient, to the degree where they miss this feature in other languages. What makes them so convenient?
+- Let's see an example of a file with a big enum. Is the file readable? How is that balanced versus type safety?
+  - [Implementation](https://github.com/rust-lang/rust/blob/master/compiler/rustc_const_eval/src/interpret/step.rs) of doing a single step in calculations of const values in the compiler.
+
 ## Pattern matching
 
 Pattern matching is a powerful feature of Rust and many functional languages, but it's slowly making
@@ -96,6 +114,28 @@ So how do we handle situations which can fail? That's where the `Result` type co
 
 {{ include_code_sample(path="lessons/03_data_types/result.rs", language="rust") }}
 
+## To discuss during class
+
+- So, why would the approach with `Result` be any cleaner than exceptions?
+- Are there any other benefits of using this approach rather than exceptions?
+- Look into the following libraries, are those interfaces convenient? How is that balanced versus type safety?
+  - [Examples of CLI parsing](https://github.com/clap-rs/clap/tree/master/examples/tutorial_derive) from `clap` repository,
+  - [README.md](https://github.com/serde-rs/json) with examples of the interface of JSON serialization/deserialization library,
+  - [Documentation](https://doc.rust-lang.org/std/path/struct.Path.html) of filesystem path handling from the standard library,
+  - [Implementation](https://github.com/BurntSushi/ripgrep/blob/master/crates/grep/examples/simplegrep.rs) of a third-party well-liked app [`ripgrep`](https://github.com/BurntSushi/ripgrep) written in Rust.
+
+## Slides
+
+<iframe
+  src="module_system/module_system.html"
+  title="Module system"
+  loading="lazy"
+  style="width: 100%; aspect-ratio: 16 / 9; border: none;"
+></iframe>
+
+- [Open the slides in a new tab (HTML)](module_system/module_system.html)
+- [Download the slides as PDF](module_system/module_system.pdf)
+
 ## Obligatory reading
 
 - The Book, chapters [5](https://doc.rust-lang.org/book/ch05-00-structs.html),
@@ -107,6 +147,6 @@ So how do we handle situations which can fail? That's where the `Result` type co
 
 ## Assignment 2 (graded)
 
-[Communications](https://classroom.github.com/a/gDraT0lo)
+[Communications](https://classroom.github.com/a/s7wihiAa)
 
-Deadline: 23.10.2024 23:59
+Deadline: per-group.

content/lessons/03_data_types/option.rs

@@ -5,33 +5,36 @@
 fn main() {
     let mut not_null: i32 = 42;
     not_null = 43;
-    // not_null = None; // this won't compile because it's a different type!
+    // not_null = None; // This won't compile because it's a different type!
 
     let mut nullable: Option<i32> = Some(42);
     nullable = None;
     nullable = Some(43);
 
-    // such construction is rare, but possible
+    // Such construction is rare, but possible.
     let mut double_nullable: Option<Option<i32>> = Some(Some(42));
-    // assert_ne!(double_nullable, Some(42)); // this won't even compile because it's a different type!
+    // This won't even compile because it's a different type.
+    // assert_ne!(double_nullable, Some(42));
     double_nullable = None;
     double_nullable = Some(None);
 
-    // None and Some(None) are different!
+    // `None` and `Some(None)` are different.
+    // Why? How are enums represented in memory?
     assert_ne!(double_nullable, None);
 
-    // Now recall that division by 0 *panics*
-    // A panic is an unrecoverable error
+    // Now recall that division by 0 *panics*.
+    // A panic is an unrecoverable error.
     // It is not an exception!
-    // And in Rust there are no exceptions, so there are no try/catch blocks
-    // Now let's imagine that we want to divide one number by another
+    // And in Rust there are no exceptions, so there are no try/catch blocks.
+    // Now let's imagine that we want to divide one number by another:
     fn divide(dividend: i32, divisor: i32) -> i32 {
         dividend / divisor
     }
 
-    // We get the divisor from the user, so it can be 0
-    // We want to handle this situation gracefully - we don't want to crash the program!
-    // We can do this by using the Option<T> type
+    // We get the divisor from the user, so it can be 0.
+    // We want to handle this situation gracefully,
+    // as we don't want to crash the program.
+    // We can do this by using the `Option<T>` type.
     fn safe_divide(dividend: i32, divisor: i32) -> Option<i32> {
         if divisor == 0 {
             None
@@ -40,11 +43,11 @@ fn main() {
         }
     }
 
-    // Fortunately, such a function is already included in the standard library
+    // Fortunately, such a function is already included in the standard library.
+    // We need to specify the type of `number` explicitly,
+    // because `checked_div` is implemented for all integer types
+    // and Rust won't know which type we want to use.
     let number: i32 = 42;
-    // We need to specify the type explicitly
-    // because checked_div is implemented for all integer types
-    // and Rust won't know which type we want to use
     assert_eq!(number.checked_div(2), Some(21));
     assert_eq!(number.checked_div(0), None);
 
@@ -55,41 +58,46 @@ fn main() {
     let seven = numbers.iter().copied().find(|&x| x == 7);
     assert_eq!(seven, None);
     // We won't delve deeper into the details of how iterators work for now,
-    // but the key takeaway is that there are no sentinel or special values like `nullptr` in Rust
+    // but the key takeaway is that there are no sentinel
+    // or special values like `nullptr`/`std::iterator` in Rust.
 
     // Usually there are two kinds of methods:
-    // ones that will panic if the argument is incorrect,
-    // numbers[8]; // this will panic!
-    // and `checked` ones that return an Option
+    // - ones that will panic if the argument is incorrect,
+    //   like: `numbers[8];` (this will panic),
+    // - and `checked` ones that return an `Option`.
     assert_eq!(numbers.get(8), None);
 
-    // We can use `unwrap` to get the value out of an Option
-    // but we must be absolutely sure that the Option is Some, otherwise we'll get a panic
-    // numbers.get(8).unwrap(); // this will panic!
-    assert_eq!(numbers.get(8).copied().unwrap_or(0), 0); // or we can provide a default value
+    // We can use `unwrap` to get the value out of an `Option`,
+    // but we must be absolutely sure that the `Option` is `Some`,
+    // otherwise we'll get a panic,
+    // like: `numbers.get(8).unwrap();` (this will panic).
+    // Or we can provide a default value:
+    assert_eq!(numbers.get(8).copied().unwrap_or(0), 0);
 
-    // Usually instead of unwrapping we use pattern matching, we'll get to this in a minute
-    // but first let's see what else we can do with an option
+    // Usually instead of unwrapping we use pattern matching,
+    // we'll get to this in a minute,
+    // but first let's see what else we can do with an option.
     let number: Option<i32> = Some(42);
-    // We can use `map` to transform the value inside an Option
+    // We can use `map` to transform the value inside an `Option`.
     let doubled = number.map(|x| x * 2);
     assert_eq!(doubled, Some(84));
-    // We can use flatten to reduce one level of nesting
+    // We can use `flatten` to reduce one level of nesting.
     let nested = Some(Some(42));
     assert_eq!(nested.flatten(), Some(42));
-    // We can use `and_then` to chain multiple options
-    // This operation is called `flatmap` in some languages
+    // We can use `and_then` to chain multiple options.
+    // This operation is called `flatmap` in some languages.
     let chained = number
         .and_then(|x| x.checked_div(0))
         .and_then(|x| x.checked_div(2));
     assert_eq!(chained, None);
 
-    // The last two things we'll cover here are `take` and `replace`
-    // They are important when dealing with non-Copy types
-    // `take` will return the value inside an Option and leave a None in its place
+    // The last two things we'll cover here are `take` and `replace`.
+    // They are important when dealing with non-`Copy` types.
+    // The `take` will return the value inside an `Option`
+    // and leave a `None` in its place.
     let mut option: Option<i32> = None;
-    // Again, we need to specify the type
-    // Even though we want to say that there is no value inside the Option,
+    // Again, we need to specify the type.
+    // Even though we want to say that there is no value inside the `Option`,
     // this absent value must have a concrete type!
     assert_eq!(option.take(), None);
     assert_eq!(option, None);
@@ -99,7 +107,7 @@ fn main() {
     assert_eq!(x, None);
     assert_eq!(y, Some(2));
 
-    // `replace` can be used to swap the value inside an Option
+    // Also `replace` can be used to swap the value inside an `Option`.
     let mut x = Some(2);
     let old = x.replace(5);
     assert_eq!(x, Some(5));