Development edit: Chapter 2

Intro -- good start. I'm seeing the promise here: I'll learn to work with functions. A better promise would tell me exactly what I'll do with functions. There's more to functions than I know now; OK, I get that. Tell me in a couple of sentences what I'll be able to DO after this chapter that I can't do now.

That first figure is bugging me a bit because the axes aren't equal. It's tangential to your point, but expect people to complain about it.

"What Is a Function?" section Did you answer the question in this section? It's implied below that a function takes an input and returns a value. Is that the canonical definition you're going for here? If so, I suggest you state it definitively.

"Function vs Procedure" section -- show me some code. Give me an example so I can see what you're talking about.

Also, do you want to mention side effects in this section, or is that on the list of functional terminology you're avoiding? I think it makes sense to say that procedures have side effects (probably ONLY have side effects, and that's the point of them), whereas functions don't (shouldn't).

"Function Input" section "the result of that expression, 6" I'd phrase this as "the result of a * 2, which is 6" just to be clear.

"Counting Inputs" section What's the point of this discussion on arity? I'm not seeing how it serves the goal of getting me closer to functional.

The lengthy discussion of the ... operator seems ES6 focused, which is fine right now because you're writing it right now, but be aware that this content will become dated more quickly than the rest of the book.

I'm really lost as to the point of this section until I got to this, hiding in the middle: "But now we start to uncover the first bits of a principle that we'll come back to many more times in this text: declarative code often communicates more cleanly than imperative code."

If that's what you're trying to say, I suggest saying so up front, so readers can be looking for it. It's one thing to leave the reader in the dark for a couple of paragraphs to get to the "aha" moment, but the discussion of arity, the ...operator, and destructuring goes on for a while before it gets to the point about declarative code.

I think the fundamental problem is that I think you're saying "this is declarative and inherently more readable:

function foo( [x,y,...args] ) {
    // ..
}

foo( [1,2,3] );

Than this, which is imperative and inherently unreadable:

function foo(params) {
    var x = params[0];
    var y = params[1];
    var args = params.slice( 2 );

    // ..
}

This is the sort of side-by-side comparison I was arguing for in Chapter 1, but it runs up against an experience problem. If readers aren't familiar with the ... operator from having used ES6, they might find it very unnatural and unreadable. The stack of manual assignments, while long and awkward, is pretty readable.

This paragraph seems to be the crux of your point in this section: "Declarative code, like destructuring in the earlier snippet, focuses on what the outcome of a piece of code should be. Imperative code, like the manual assignments just shown, focuses more on how to get the outcome. If you later read the code, you have to mentally execute it to understand the desired outcome. The outcome is coded there, but it's not as clear."

But I'm not sure you're adequately making your case to someone with a habit of imperative programming, to whom the assignment snippet is natural to read. I think you need to make the point better that "the outcome" and "how you get to the outcome" are two different things, and that's not clear yet. You need to define what you mean by "the outcome."

"Functions Varying by Input" section I get what you're saying in this section -- that function overloading is dangerous if you sacrifice readability for convenience. But what does that have to do with FP? I don't see the connection.

"Function Output" section Tip regarding "separated into two or more smaller single-purpose functions" Normally, I'd suggest giving an example, because that would make your point clearer, but this is just a tip, so maybe it's not appropriate here.

"Functions of Functions" section Now we're getting FP! It hasn't been clear so far in this chapter that this is what we're leading up to. Maybe spend some more time on the concept that functions can take and return functions? That's pretty fundamental to FP as I understand it, and can be tricky to grasp for beginners.

"What's This" section If the conclusion is "don't use this," then why spend time discussing it? I don't think it's necessary to spend time on the specific reasons why using thisis a bad idea.

getify / Functional-Light-JS

Development edit: Chapter 2 #54