maxogden/art-of-node — pull request #34 by francismakes (2014-04-21 07:55:34+00:00)
Title: (Callbacks) Clarify the `addOne` explanation.

__Issue #1__: Step 1 of the current `addOne` explanation is contradictory (Line 182).

> During this initial phase there are 4 things that get defined: `fs`, `myNumber`, `addOne`, and `logMyNumber`. Note that these are just being defined, no functions have been called/invoked yet.

But how can `myNumber` be "defined" when it is assigned to the `undefined` value?

__Proposed Changes__: Replace the verb "defined" with "declared" to succinctly express the respective variable and function declarations.

---

__Issue #2__: Step 2 of the current `addOne` explanation contains awkward wording. (Line 183).

> When the last line of our program gets executed `addOne` gets invoked, getting passed in the `logMyNumber` function as callback, which is what we want to be called when `addOne` is complete. This immediately causes the asynchronous `fs.readFile` function to kick off. This part of the program takes a while to finish.

Line 176 already defines that a callback runs when its asynchronous function completes. `addOne`'s invocation causes `fs.readFile` function to kick off, not its callback.

__Proposed Changes__: Revise the explanation to state that `addOne` is executed with `logMyNumber` as its callback, and that `addOne`'s invocation will first run the async `fs.readFile` function.

---

__Issue #3__: Step 4 of the current `addOne` explanation is missing a step (Line 185).

> `readFile` finishes and calls its callback, `doneReading`, which then in turn increments the number and then immediately invokes the function that `addOne` passed in (its callback), `logMyNumber`.

But `doneReading` first parses fileContents for an integer and caches it into a variable called `myNumber`.

__Proposed Changes__: Include the missing step.