updated docs

Author: soudmaijer

exercise-3.md

@@ -10,16 +10,14 @@ Open `Basket.java`
 
 After the conversion the code is still far from optimal. The Java2kotlin converter still uses the Java Stream API and tries to make the best out of it. 
 
-We can clean it up a bit by writing the calculation in exactly the same way as we would do with the Java Stream API. 
-
-Kotlin also has a build in reduce function in the std lib, so we can use that instead of the Java Stream API.
+We could clean it up a bit by writing the calculation in exactly the same way as we would do with the Java Stream API. But Kotlin has a build in reduce function in the std lib, so we can use that instead of the Java Stream API.
 
 ```kotlin
 val totalPrice: BigDecimal
     get() = items.map(OrderItem::totalPrice).reduce { acc, next -> acc + next }
 ```
 
-**Exercise:** change the calculation to the snippet above
+**Exercise:** change the `totalPrice` calculation to the snippet above
 
 There are a few problems with this code. First, the map operation produces a new list as its result on which the reduce operation is performed while we actually don't even use this list anywhere else. 
 Our newly introduced reduce does not work on an empty collection. Even though the code compiles, it is effectively broken. 
@@ -47,7 +45,7 @@ val totalPrice: BigDecimal
     get() = items.sumBy { it.totalPrice }
 ```
 
-Kotlin already has build-in functions to sum types:
+Kotlin already has build-in functions to sum BigDecimal types:
 
 ```kotlin
 public inline fun <T> Iterable<T>.sumOf(selector: (T) -> java.math.BigDecimal): java.math.BigDecimal
@@ -94,7 +92,7 @@ constructor(items: MutableList<OrderItem>) {
 }
 ```
 
-**Exercise**: Write a primary constructor for the Basket class and combine the constructors into one property items: MutableList<OrderItem>. Does the code still work?
+**Exercise**: Write a primary constructor for the Basket class and combine the constructors into one property for the items. Verify that the code still works!
 
 <details>
   <summary>Suggested solution:</summary>
@@ -128,7 +126,7 @@ First have a look at the `getBasketById()`, it uses `computeIfAbsent`. See if yo
 ```kotlin
 fun getBasketById(id: String): Basket = baskets.getOrPut(id) { Basket() }
 ```
-Or 
+Or without the need for a Lambda:
 
 ```kotlin
 fun getBasketById(id: String): Basket = baskets.getOrDefault(id, Basket())
@@ -220,9 +218,11 @@ While `@PathVariable` is required by default, the id argument is nullable here.
 
 **Exercise**: Change the `id` argument to the non-nullable type String and in the expression body remove the non-null assertion. Do the same for `addToBasket()`.
 
-In `addToBasket` we can also handle the case where we try to add a non-existing product to our basket a bit better. 
+As a bonus we could omit the `"id"` from `@PathVariable("id")` because Spring is able to figure out the name of the argument from the Kotlin generated bytecode.
+
+In `addToBasket` we improve on handling the case where we try to add a non-existing productId to our basket. 
 
-**Exercise**: Add a null check for non-existing products and throw an ResponseStatusException() if not found.
+**Exercise**: Add a null check for a non-existing product and throw an ResponseStatusException() if not found.
 
 <details>
 <summary>The resulting code should look like this:</summary>
@@ -242,7 +242,7 @@ fun addToBasket(@PathVariable("id") id: String, @RequestBody orderItem: OrderIte
 
 Last but not least we have the BootiqueApplicationTests class. Once this test class has been converted we could get rid of the Java compiler if needed.
 
-**Exercise**: Convert BootiqueApplicationTests to Kotlin. Build the application and verify everything is still working as expected.
+**Exercise**: Convert BootiqueApplicationTests to Kotlin. Build the application and verify everything is still working as expected!
 
 ### Next steps