Chapter 10 - Feedback

I feel Chapter 10 needs a bit of love in order to explain things more clearly.

Starting with this bit of code and the following explanation:

fun countingLambda(): () -> Int {
  var counter = 0
  val incrementCounter: () -> Int = {
    counter += 1
  return incrementCounter

This function takes no parameters and returns a lambda. The lambda it returns takes no parameters and returns an Int. The lambda returned from this function will increment its internal counter each time it is called. Each time you call this function you get a different counter.

The code certainly works, but I feel lost as a reader at this point. I think this requires a more clear explanation.

Then just a bit later this code is introduced:

public inline fun <T> Iterable<T>.filter(predicate: (T) -> Boolean): List<T>

At this point, the reader is completely lost. Keep in mind, there has been no explanation of generics by this point in the book. Furthermore the reader does not know, at this point, what is “Iterable” and the rest of the function signature is pretty much Greek. I realized the explanation after this code tries to explain the generic part, without talking about generics, but I really don’t feel it’s sufficient.

Many of the readers may be coming to this book for Kotlin as their very first programming language. Up until this point, the book has been very clear and introduced the concepts in a simple, step wise fashion. That pretty much broke down in this chapter, though. I realize it can be quite challenging to break down a complex topic like this, but without it we might be losing some readers at this point.

Later still in the chapter different lambda functions are mentioned. When we get to the fold function, this explanation is offered:

The lambda takes two values: the current value and an element from the list.

What list? No list has been discussed up to this point.

The official Kotlin documentation actually has much more clear explanation of fold and reduce:

Note they define an actual list before presenting the fold and reduce operations on that list.

The Kotlin Apprentice example also used a list defined earlier, but the grammar in the above explanation, which appears before that, is not at all clear.

I think overall the chapter just needs some work to make things easier to understand.

@abunur Thank you for your feedback - much appreciated! I will forward it to the book team.