up

Author: iliakan

1-js/03-code-quality/01-debugging-chrome/chrome-open-sources.png

@@ -1,8 +1,10 @@
 
-# Callback hell
 
+# Introduction: sync vs async, callbacks
 
-Consider this function `loadScript(src)` that loads a script:
+Many actions in Javascript are *asynchronous*.
+
+For instance, take a look at the function `loadScript(src)` that loads a script:
 
 ```js
 function loadScript(src) {
@@ -12,7 +14,7 @@ function loadScript(src) {
 }
 ```
 
-When the script element is added to the document, the browser loads it and executes. So, the function works.
+The purpose of the function is to load a new script. When it adds the `<script src="…">` to the document, the browser loads and executes it.
 
 We can use it like this:
 
@@ -21,27 +23,28 @@ We can use it like this:
 loadScript('/my/script.js');
 ```
 
-The function is *asynchronous*: the script starts loading now, but finishes later.
-
-"Synchonous" and "asynchronous" are general programming terms, not specific to JavaScript.
+The function is called "asynchronous", because the action (script loading) finishes not now, but later.
 
-A *synchronous* action suspends the execution until it's completed. For instance, a call to `alert` or `prompt` is synchronous: the program may not continue until it's finished.
+The call initiates the script loading, then the execution continues normally.
 
 ```js
-let age = prompt("How old are you", 20);
-// the execution of the code below awaits for the prompt to finish
-// the script hangs
+loadScript('/my/script.js');
+// the code below doesn't wait for the script loading to finish
 ```
 
-An *asynchronous* action allows the program to continue while it's in progress. For instance, a call to `loadScript` is asynchronous. It initiates the script loading, but does not suspend the execution. Other commands may execute while the script is loading:
+Now let's say we want to use the new script when loads. It probably declares new functions, so we'd like to run them.
+
+...But if we do that immediately after the `loadScript(…)` call, that wouldn't work:
 
 ```js
-loadScript('/my/script.js');
-// the execution of the code below *does not* wait for the script loading to finish,
-// it just continues
+loadScript('/my/script.js'); // the script has "function newFunction() {…}"
+
+*!*
+newFunction(); // no such function!
+*/!*
 ```
 
-As of now, the `loadScript` function loads the script, doesn't provide a way to track the load completion. The script loads and eventually runs, that's all. But we'd like to know when happens, to use additional functions and variables from that script.
+Naturally, the browser probably didn't have the time to load the script. As of now, the `loadScript` function doesn't provide a way to track the load completion. The script loads and eventually runs, that's all. But we'd like to know when happens, to use new functions and variables from that script.
 
 Let's add a `callback` function as a second argument to `loadScript` that should execute when the script loads:
 
@@ -58,7 +61,19 @@ function loadScript(src, callback) {
 }
 ```
 
-Now we're able to load a script and then run our code that can use new functions from it, like here:
+Now if we want to call new functions from the script, we should write that in the callback:
+
+```js
+loadScript('/my/script.js', function() {
+  // the callback runs after the script is loaded
+  newFunction(); // so now it works
+  ...
+});
+```
+
+That's the idea: the second argument is a function (usually anonymous) that runs when the action is completed.
+
+Here's a runnable example with the real script:
 
 ```js run
 function loadScript(src, callback) {
@@ -69,7 +84,7 @@ function loadScript(src, callback) {
 }
 
 *!*
-loadScript('https://cdnjs.cloudflare.com/ajax/libs/lodash.js/3.2.0/lodash.js', function(script) {
+loadScript('https://cdnjs.cloudflare.com/ajax/libs/lodash.js/3.2.0/lodash.js', script => {
   alert(`Cool, the ${script.src} is loaded`);
   alert( _ ); // function declared in the loaded script
 });
@@ -78,13 +93,13 @@ loadScript('https://cdnjs.cloudflare.com/ajax/libs/lodash.js/3.2.0/lodash.js', f
 
 That's called a "callback-based" style of asynchronous programming. A function that does something asynchronously should provide a `callback` argument where we put the function to run after it's complete.
 
-Here it was used for `loadScript`, but of course it's a general approach.
+Here we did so in `loadScript`, but of course it's a general approach.
 
 ## Callback in callback
 
-What if we need to load two scripts sequentially: the first one, and then the second one after it?
+How to load two scripts sequentially: the first one, and then the second one after it?
 
-We can put the second `loadScript` inside the callback, like this:
+The natural solution would be to put the second `loadScript` call inside the callback, like this:
 
 ```js
 loadScript('/my/script.js', function(script) {
@@ -100,7 +115,7 @@ loadScript('/my/script.js', function(script) {
 });
 ```
 
-Now after the outer `loadScript` is complete, the callback initiates the inner one.
+After the outer `loadScript` is complete, the callback initiates the inner one.
 
 ...What if we want one more script?
 
@@ -120,11 +135,9 @@ loadScript('/my/script.js', function(script) {
 });
 ```
 
-As we can see, a new asynchronous action means one more nesting level. So the code becomes deeper and deeper.
-
 ## Handling errors
 
-In examples above we didn't consider errors. What if a script loading failed with an error? Our callback should be able to react on that.
+In examples above we didn't consider errors. What if a script loading fails with an error? Our callback should be able to react on that.
 
 Here's an improved version of `loadScript` that tracks loading errors:
 
@@ -144,7 +157,7 @@ function loadScript(src, callback) {
 
 It calls `callback(null, script)` for successful load and `callback(error)` otherwise.
 
-Usage:
+The usage:
 ```js
 loadScript('/my/script.js', function(error, script) {
   if (error) {
@@ -155,11 +168,13 @@ loadScript('/my/script.js', function(error, script) {
 });
 ```
 
+Once again, the recipe that we used for `loadScript` is actually quite common. It's called the "error-first callback" style.
+
 The convention is:
 1. The first argument of `callback` is reserved for an error if it occurs. Then `callback(err)` is called.
 2. The second argument and successive ones if needed are for the successful result. Then `callback(null, result1, result2…)` is called.
 
-So the single `callback` function is used both for reporting errors and passing back results. That's called "error-first callback" style. Or we could use different functions for successful and erroneous completion.
+So the single `callback` function is used both for reporting errors and passing back results.
 
 ## Pyramid of doom
 
@@ -200,17 +215,17 @@ In the code above:
 2. We load `2.js`, then if there's no error.
 3. We load `3.js`, then if there's no error -- do something else `(*)`.
 
-As calls become more nested, the whole thing becomes increasingly more difficult to manage, especially if we add real code instead of `...`, that may include more loops, conditional statements and other usage of loaded scripts.
+As calls become more nested, the code becomes deeper and increasingly more difficult to manage, especially if we have a real code instead of `...`, that may include more loops, conditional statements and so on.
 
 That's sometimes called "callback hell" or "pyramid of doom".
 
 ![](callback-hell.png)
 
-The pyramid grows to the right with every asynchronous action. Soon it spirales out of control.
+The "pyramid" of nested calls grows to the right with every asynchronous action. Soon it spirales out of control.
 
 So this way of coding appears not so good.
 
-In simple cases we can evade the problem by making every action a standalone function, like this:
+We can try to alleviate the problem by making every action a standalone function, like this:
 
 ```js
 loadScript('1.js', step1);
@@ -242,10 +257,10 @@ function step3(error, script) {
 };
 ```
 
-See? It does the same, and there's no deep nesting now, because we moved every function to the top. But the code looks like a torn apart spreadsheet. We need to eye-jump between pieces while reading it. It's not very readable, especially if you are not familiar with it and don't know where to eye-jump.
+See? It does the same, and there's no deep nesting now, because we made every action a separate top-level function. It works, but the code looks like a torn apart spreadsheet. It's difficult to read. One needs to eye-jump between pieces while reading it. That's inconvenient, especially the reader is not familiar with the code and doesn't know where to eye-jump.
 
-Also the functions `step*` have no use, they are only created to evade the "pyramid of doom".
+Also the functions named `step*` are all of a single use, they are only created to evade the "pyramid of doom". So there's a bit of a namespace cluttering here.
 
-So we'd like to have a better way of coding for complex asynchronous actions.
+We'd like to have a better way of coding for complex asynchronous actions.
 
-Luckily, there are other ways to evade such pyramids. For instance, we can use "promises", described in the next chapter.
+Luckily, there are other ways to evade such pyramids. One of the best ways is to use "promises", described in the next chapter.