up

Author: iliakan

1-js/02-first-steps/01-hello-world/article.md

@@ -1,10 +1,10 @@
 # Hello, world!
 
-The tutorial that you're reading is about core Javascript, that is platform-independant. So you'll be able to learn how to use Node.JS and other things based on that knowledge.
+The tutorial that you're reading is about the core Javascript, that is platform-independant. So you'll be able to learn how to use Node.JS and other things based on that knowledge.
 
-But we need a working environment to run our scripts, and browser is probably a good choice. Also we'll use few browser-specific commands like `alert`, but will keep their amount to the minimum.
+But we need a working environment to run our scripts, and, just because this book is online, the browser is probably a good choice. We'll use a few browser-specific commands like `alert`, but will keep their amount to the minimum.
 
-So we'll start with attaching a script to the webpage. For other environments like Node.JS there are other, probably even easier ways to run it.
+So here we'll see how to attach a script to the webpage, that's simple enough. For server-side environments  you can just execute it with a command like `"node my.js"` for Node.JS.
 
 [cut]
 

1-js/02-first-steps/02-structure/article.md

@@ -1,6 +1,6 @@
 # Code structure
 
-The first overall thing to know is the code structure.
+The first thing to study is the building blocks of the code.
 
 [cut]
 
@@ -54,43 +54,46 @@ The code outputs `6`, because JavaScript does not insert semicolons here. It is
 
 Errors which occur in such cases are quite hard to find and fix.
 
-````smart header="An example of the error"
-If you're curious to see a concrete example, check this code out:
+````smart header="An example of an error"
+If you're curious to see a concrete example of such an error, check this code out:
 
 ```js run
 [1, 2].forEach(alert)
 ```
 
 It shows `1` then `2`.
 
-No need to think about the meaning of the brackets `[]` and `forEach`, for now -- it does not matter. Let's just remember the result.
+No need to think about the meaning of the brackets `[]` and `forEach` yet. We'll study them, for now -- it does not matter. Let's just remember the result.
 
-Now let's put an `alert` before the code. And *not* finish it with a semicolon:
+Now let's add an `alert` before the code. And *not* finish it with a semicolon:
 
 ```js run no-beautify
-alert( "There will be an error" ) // shown
+alert( "There will be an error" ) 
 
-[1, 2].forEach(alert) // doesn't work any more!
+[1, 2].forEach(alert) 
 ```
 
 Now if we run it, only the first `alert` is shown, and then an error.
 
 But everything is fine again if we add a semicolon after `alert`:
 ```js run
-alert( "All fine now" ); // shown
+alert( "All fine now" ); 
 
-[1, 2].forEach(alert)  // this works too
+[1, 2].forEach(alert)  
 ```
 
+Now we have the "All fine now" message and then `1` and `2`.
+
+
 The error in the no-semicolon variant occurs because automatic semicolon insertion rules are complex, and in particular, JavaScript does not imply a semicolon before square brackets `[...]`.
 
-And, because the semicolon is not auto-inserted, the code is treated as a single statement, like this:
+And, because the semicolon is not auto-inserted, the code in the first example is treated as a single statement, like this:
 
 ```js run no-beautify
 alert( "There will be an error" )[1, 2].forEach(alert)
 ```
 
-And in this particular case, that's just wrong, hence the error. There are other situations when such thing happens.
+But it should be two separate statements, not a single one. Such a merging in this case is just wrong, hence the error. There are other situations when such thing happens.
 ````
 
 It's recommended to put semicolons between statements even if they are separated by newlines. This rule is widely adopted by the community. Let's note once again -- *it is possible* to leave out semicolons most of time. But it's safer, especially for a beginner -- to put them.
@@ -105,12 +108,12 @@ Comments can be put into any place of the script. They don't affect the executio
 
 The rest of the line is a comment. It may occupy a full line of its own or follow a statement.
 
-Like this:
+Like here:
 ```js run
-// This shows "Hello" (the comment occupies a line of its own)
+// This comment occupies a line of its own
 alert( 'Hello' );
 
-alert( 'World' ); // ...this shows "World" (the comment follows a statement)
+alert( 'World' ); // This comment follows the statement
 ```
 
 **Multiline comments start with a slash and a star <code>"/&#42;"</code> and end with a star and a slash <code>"&#42;/"</code>.**
@@ -125,7 +128,7 @@ alert( 'Hello' );
 alert( 'World' );
 ```
 
-The content of comments is ignored, so if we put a code inside <code>/&#42; ... &#42;/</code> or after `//` it won't execute.
+The content of comments is ignored, so if we put a code inside <code>/&#42; ... &#42;/</code> it won't execute.
 
 Sometimes it comes handy to temporarily disable a part of the code:
 

1-js/02-first-steps/05-types/article.md

@@ -43,13 +43,13 @@ Besides regular numbers there are so-called "special numeric values" which also
 - `NaN` represents a computational error. It is a result of an incorrect or an undefined mathematical operation, for instance:
 
     ```js run
-    alert( "not a number" / 2 ); // NaN
+    alert( "not a number" / 2 ); // NaN, such division is erroneous
     ```
 
     `NaN` is sticky. Any further operation on `NaN` would give `NaN`:
 
     ```js run
-    alert( "not a number" / 2 + 5 ); // NaN + 5 is still NaN
+    alert( "not a number" / 2 + 5 ); // NaN
     ```
 
     So, if there's `NaN` somewhere in a mathematical expression, it propagates to the whole result.
@@ -66,6 +66,8 @@ We'll see more into working with numbers in the chapter <info:number>.
 
 ## A string
 
+A string in Javascript must be quoted.
+
 ```js
 let str = "Hello";
 let str2 = 'Single quotes are ok too';
@@ -78,7 +80,7 @@ In JavaScript, there are 3 types of quotes.
 2. Single quotes: `'Hello'`.
 3. Backticks: <code>&#96;Hello&#96;</code>.
 
-Double and single quotes are similar, "simple" quotes.
+Double and single quotes are "simple" quotes. They mark the beginning and the end of the string, that's all. There's no difference between them in Javascript.
 
 Backticks are "extended functionality" quotes. They allow to embed variables and expressions into a string by wrapping them in `${…}`, for example:
 
@@ -94,10 +96,15 @@ alert( `the result is ${1 + 2}` ); // the result is 3
 
 The expression inside `${…}` is evaluated and the result becomes a part of the string. We can put anything there: a variable like `name` or an arithmetical expression like `1 + 2` or something more complex.
 
+Please note that other quotes do not allow such embedding!
+```js run
+alert( "the result is ${1 + 2}" ); // the result is ${1 + 2} (double quotes do nothing)
+```
+
 We'll cover strings more thoroughly in the chapter <info:string>.
 
 ```smart header="There is no *character* type."
-In some languages, there is a special "character" type for a single character. For example, in the C language it is `char`.
+In some languages, there is a special "character" type for a single character. For example, in the C language and in Java it is `char`.
 
 In JavaScript, there is no such type. There's only one type: `string`. A string may consist of only one character or many of them.
 ```
@@ -111,8 +118,8 @@ This type is commonly used to store yes/no values: `true` means "yes, correct",
 For instance:
 
 ```js
-let checked1 = true;  // yes, the form field is checked
-let checked2 = false; // no, the form field is not checked
+let nameChecked = true; // yes, the form field name is checked
+let ageChecked = false; // no, the form field age is not checked
 ```
 
 Boolean values also come as the result of comparisons:

1-js/02-first-steps/14-function-basics/article.md

@@ -380,6 +380,59 @@ For example, [jQuery](http://jquery.com) framework defines a function `$`, [LoDa
 These are exceptions. Generally functions names should be concise, but descriptive.
 ```
 
+## Functions == Comments
+
+Functions should be short and do exactly one thing. If that thing is big, maybe it's worth to split the function into parts.
+
+Sometimes following this rule may be not easy, but it's a definitely good thing.
+
+...So why functions equal comments?
+
+A separate function is not only easier to test and debug -- its very existence is a great comment!
+
+For instance, compare the two functions `showPrimes(n)` below. Each one outputs [prime numbers](https://en.wikipedia.org/wiki/Prime_number) up to `n`.
+
+The first variant uses a label:
+
+```js
+function showPrimes(n) {
+  nextPrime: for (let i = 2; i < n; i++) {
+
+    for (let j = 2; j < i; j++) {
+      if (i % j == 0) continue nextPrime;
+    }
+
+    alert( i ); // a prime
+  }
+}
+```
+
+The second variant uses an additional function `isPrime(n)` to test for primality:
+
+```js
+function showPrimes(n) {
+
+  for (let i = 2; i < n; i++) {
+    *!*if (!isPrime(i)) continue;*/!*
+
+    alert(i);  // a prime
+  }
+}
+
+function isPrime(n) {
+  for (let i = 2; i < n; i++) {
+    if ( n % i == 0) return false;
+  }
+  return true;
+}
+```
+
+The second variant is easier to understand isn't it? Instead of the code piece we see a name of the action (`isPrime`). Sometimes people refer to such code as *self-describing*.
+
+```summary
+So the idea is: functions can be created even if we don't intend to reuse them. They structure the code and make it readable.
+```
+
 ## Summary
 
 A function declaration looks like this:

1-js/02-first-steps/15-function-expressions-arrows/article.md

@@ -95,7 +95,7 @@ The answer is simple:
 - A Function Expression is used inside the statement: `let sayHi = ...;`, as a value. It's not a code block. The semicolon `;` is recommended at the end of statements, no matter what is the value. So the semicolon here is not related to Function Expression itself in any way, it just terminates the statement.
 ````
 
-## Anonymous functions
+## Callback functions
 
 Let's see an example where function expressions come really handy.
 
@@ -134,9 +134,13 @@ ask("Do you agree?", showOk, showCancel);
 
 The code looks kind of too simple, right? Why would anyone need such `ask`?
 
-...It turns out that in the browser such functions are very required, the minor difference is that they ask not with a simple `confirm`, but output a much richer looking question window. But that's another story.
+...It turns out that in the browser (and on the server-side in some cases) such functions are quite popular. The major difference between a real-life implementation and the example above is that real-life functions use more complex ways to interact with the user than a simple `confirm`. In the browser such a function usually draws a nice-looking question window. But that's another story.
 
-Right now let's see how we can write the same much shorter:
+The arguments of `ask` are called *callback functions* or just *callbacks*. The idea is that we pass the functions and expect them to be "called back" in certain circumstances.
+
+So, `showOk` becomes the callback for the "yes" answer and `showCancel` -- for the "no" answer.
+
+We can use Function Expressions to write the same much shorter:
 
 ```js run no-beautify
 function ask(question, yes, no) {
@@ -153,9 +157,9 @@ ask(
 */!*
 ```
 
-Here functions are declared right inside the `ask(...)` call. They have no name (anonymous) and are not accessible outside of `ask`, but that's just what we need.
+Here functions are declared right inside the `ask(...)` call. They have no name, and so are called *anonymous*. Such functions are not accessible outside of `ask`, but that's just what we want here.
 
-Such code appears very naturally, it's in the spirit of Javascript.
+Such code appears in our scripts very naturally, it's in the spirit of Javascript.
 
 
 ```smart header="A function is a value representing an \"action\""
@@ -405,7 +409,17 @@ let double = n => n*2;
 alert( double(3) ); // 6
 ```
 
-If there are no arguments, we can put empty brackets. For instance, here's the rewritten example with `welcome()`:
+If there are no arguments, we can put empty brackets:
+
+```js run
+let sayHi = () => alert("Hello!");
+
+sayHi();
+```
+
+Arrow functions can be used same way as Function Expressions.
+
+For instance, here's the rewritten example with `welcome()`:
 
 ```js run
 let age = prompt("What is your age?", 18);
@@ -439,45 +453,26 @@ alert( sum(1, 2) ); // 3
 ```
 
 ```smart header="More to come"
-Here we praised arrow functions for shortness. But that's not all! Arrow functions have other interesting features. We'll return to them later and see where else they shine.
+Here we praised arrow functions for shortness. But that's not all! Arrow functions have other interesting features. We'll return to them later in the chapter <info:arrow-functions>.
 
-As for now, we can already use them for one-line actions.
+As for now, we can already use them for one-line actions and callbacks.
 ```
 
 ## Summary
 
-[todo review]
-
 - Functions are values. They can be assigned, copied or declared in any place of the code.
 - If the function is declared as a separate statement, in the main code flow -- that's called a Function Declaration.
 - If the function is created as a part of an expression -- it's a Function Expression.
-- Function Declarations are processed before the code block is executed. They are visible everywhere in the block (or the script).
+- Function Declarations are processed before the code block is executed. They are visible everywhere in the block.
 - Function Expressions are created when the execution flow reaches them.
 - Function Expressions allow to specify an optional name for internal needs (Named Function Expression).
 
 
-If we simple want to create a function, then in most cases Function Declaration is preferable.
-
-Novice programmers sometimes tend to overuse Function Expression by creating many functions with `let func = function()`, but compare, which code is more readable:
-
-```js no-beautify
-let f = function() { /* expression */ }
-
-function f() { /* declaration */ }
-```
-
-Function Declaration is shorter and more obvious. The additional bonus -- it can be called before the actual declaration.
-
-**Use Function Expression only when Function Declaration does not fit the task.**
-
-We've seen a couple of examples of that in the chapter. And will see more in the future.
-
-We also touched two other ways to create a function:
+In most cases Function Declaration is preferable, because it is visible prior to the declaration itself. And is usually more readable.
 
-- Arrow functions are handy for one-liners. The come in two flavours:
-    1. Without figure brackets: `(...args) => expression` -- returns the evaluated `expression`.
-    2. With brackets: `(...args) => { body }` -- need an explicit `return` statement to return something, but can be more complex.
+So we should use Function Expression only when Function Declaration does not fit the task. We've seen a couple of examples of that in the chapter. And will see more in the future.
 
-- `new Function(args, body)`
+Arrow functions are handy for one-liners. The come in two flavors:
 
-    This syntax allows to create a function from a string, that may be composed dynamically during the execution.
+1. Without figure brackets: `(...args) => expression` -- returns the evaluated `expression`. The right side must be a single expression.
+2. With figure brackets: `(...args) => { body }` -- they need an explicit `return` statement to return something, but can be more complex and contain multiple statements.