Merge branch 'master' of github.com:javascript-tutorial/en.javascript.info into sync-b300836f

Author: iliakan

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

@@ -196,19 +196,20 @@ First, the syntax: how to differentiate between them in the code.
 
 The more subtle difference is *when* a function is created by the JavaScript engine.
 
-**A Function Expression is created when the execution reaches it and is usable from then on.**
+**A Function Expression is created when the execution reaches it and is usable only from that moment.**
 
 Once the execution flow passes to the right side of the assignment `let sum = function…` -- here we go, the function is created and can be used (assigned, called, etc. ) from now on.
 
 Function Declarations are different.
 
-**A Function Declaration is usable in the whole script (or a code block, if it's inside a block).**
+**A Function Declaration can be called earlier than it is defined.**
 
-In other words, when JavaScript *prepares* to run the script or a code block, it first looks for Function Declarations in it and creates the functions. We can think of it as an "initialization stage".
+For example, a global Function Declaration is visible in the whole script, no matter where it is.
 
-And after all of the Function Declarations are processed, the execution goes on.
+That's due to internal algorithms. When JavaScript prepares to run the script, it first looks for global Function Declarations in it and creates the functions. We can think of it as an "initialization stage".
+
+And after all Function Declarations are processed, the code is executed. So it has access to these functions.
 
-As a result, a function declared as a Function Declaration can be called earlier than it is defined.
 
 For example, this works:
 
@@ -224,7 +225,7 @@ function sayHi(name) {
 
 The Function Declaration `sayHi` is created when JavaScript is preparing to start the script and is visible everywhere in it.
 
-...If it was a Function Expression, then it wouldn't work:
+...If it were a Function Expression, then it wouldn't work:
 
 ```js run refresh untrusted
 *!*
@@ -238,13 +239,11 @@ let sayHi = function(name) {  // (*) no magic any more
 
 Function Expressions are created when the execution reaches them. That would happen only in the line `(*)`. Too late.
 
-**When a Function Declaration is made within a code block, it is visible everywhere inside that block. But not outside of it.**
-
-Sometimes that's handy to declare a local function only needed in that block alone. But that feature may also cause problems.
+**In strict mode, when a Function Declaration is within a code block, it's visible everywhere inside that block. But not outside of it.**
 
 For instance, let's imagine that we need to declare a function `welcome()` depending on the `age` variable that we get during runtime. And then we plan to use it some time later.
 
-The code below doesn't work:
+If we use Function Declaration, it won't work as intended:
 
 ```js run
 let age = prompt("What is your age?", 18);
@@ -350,12 +349,12 @@ welcome(); // ok now
 ```
 
 
-```smart header="When should you choose Function Declaration versus Function Expression?"
-As a rule of thumb, when we need to declare a function, the first to consider is Function Declaration syntax, the one we used before. It gives more freedom in how to organize our code, because we can call such functions before they are declared.
+```smart header="When to choose Function Declaration versus Function Expression?"
+As a rule of thumb, when we need to declare a function, the first to consider is Function Declaration syntax. It gives more freedom in how to organize our code, because we can call such functions before they are declared.
 
-It's also a little bit easier to look up `function f(…) {…}` in the code than `let f = function(…) {…}`. Function Declarations are more "eye-catching".
+That's also better for readability, as it's easier to look up `function f(…) {…}` in the code than `let f = function(…) {…}`. Function Declarations are more "eye-catching".
 
-...But if a Function Declaration does not suit us for some reason (we've seen an example above), then Function Expression should be used.
+...But if a Function Declaration does not suit us for some reason, or we need a conditional declaration (we've just seen an example), then Function Expression should be used.
 ```
 
 

1-js/05-data-types/03-string/1-ucfirst/solution.md

@@ -6,7 +6,7 @@ But we can make a new string based on the existing one, with the uppercased firs
 let newStr = str[0].toUpperCase() + str.slice(1);
 ```
 
-There's a small problem though. If `str` is empty, then `str[0]` is undefined, so we'll get an error.
+There's a small problem though. If `str` is empty, then `str[0]` is `undefined`, and as `undefined` doesn't have the `toUpperCase()` method, we'll get an error.
 
 There are two variants here:
 

1-js/05-data-types/03-string/1-ucfirst/task.md

@@ -2,7 +2,7 @@ importance: 5
 
 ---
 
-# Uppercast the first character
+# Uppercase the first character
 
 Write a function `ucFirst(str)` that returns the string `str` with the uppercased first character, for instance:
 

1-js/05-data-types/03-string/article.md

@@ -86,13 +86,13 @@ Examples with unicode:
 
 ```js run
 alert( "\u00A9" ); // ©
-alert( "\u{20331}" ); // 佫, a rare chinese hieroglyph (long unicode)
+alert( "\u{20331}" ); // 佫, a rare Chinese hieroglyph (long unicode)
 alert( "\u{1F60D}" ); // 😍, a smiling face symbol (another long unicode)
 ```
 
 All special characters start with a backslash character `\`. It is also called an "escape character".
 
-We would also use it if we want to insert a quote into the string.
+We might also use it if we wanted to insert a quote into the string.
 
 For instance:
 
@@ -305,7 +305,8 @@ if (str.indexOf("Widget") != -1) {
 }
 ```
 
-````smart header="The bitwise NOT trick"
+#### The bitwise NOT trick
+
 One of the old tricks used here is the [bitwise NOT](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_Operators#Bitwise_NOT) `~` operator. It converts the number to a 32-bit integer (removes the decimal part if exists) and then reverses all bits in its binary representation.
 
 For 32-bit integers the call `~n` means exactly the same as `-(n+1)` (due to IEEE-754 format).
@@ -321,9 +322,9 @@ alert( ~-1 ); // 0, the same as -(-1+1)
 */!*
 ```
 
-As we can see, `~n` is zero only if `n == -1`.
+As we can see, `~n` is zero only if `n == -1` (that's for any 32-bit signed integer `n`).
 
-So, the test `if ( ~str.indexOf("...") )` is truthy that the result of `indexOf` is not `-1`. In other words, when there is a match.
+So, the test `if ( ~str.indexOf("...") )` is truthy only if the result of `indexOf` is not `-1`. In other words, when there is a match.
 
 People use it to shorten `indexOf` checks:
 
@@ -338,7 +339,10 @@ if (~str.indexOf("Widget")) {
 It is usually not recommended to use language features in a non-obvious way, but this particular trick is widely used in old code, so we should understand it.
 
 Just remember: `if (~str.indexOf(...))` reads as "if found".
-````
+
+Technically speaking, numbers are truncated to 32 bits by `~` operator, so there exist other big numbers that give `0`, the smallest is `~4294967295=0`. That makes such check is correct only if a string is not that long.
+
+Right now we can see this trick only in the old code, as modern JavaScript provides `.includes` method (see below).
 
 ### includes, startsWith, endsWith
 
@@ -558,7 +562,7 @@ You can skip the section if you don't plan to support them.
 
 ### Surrogate pairs
 
-Most symbols have a 2-byte code. Letters in most european languages, numbers, and even most hieroglyphs, have a 2-byte representation.
+All frequently used characters have 2-byte codes. Letters in most european languages, numbers, and even most hieroglyphs, have a 2-byte representation.
 
 But 2 bytes only allow 65536 combinations and that's not enough for every possible symbol. So rare symbols are encoded with a pair of 2-byte characters called "a surrogate pair".
 
@@ -567,7 +571,7 @@ The length of such symbols is `2`:
 ```js run
 alert( '𝒳'.length ); // 2, MATHEMATICAL SCRIPT CAPITAL X
 alert( '😂'.length ); // 2, FACE WITH TEARS OF JOY
-alert( '𩷶'.length ); // 2, a rare chinese hieroglyph
+alert( '𩷶'.length ); // 2, a rare Chinese hieroglyph
 ```
 
 Note that surrogate pairs did not exist at the time when JavaScript was created, and thus are not correctly processed by the language!
@@ -628,7 +632,7 @@ For instance:
 
 ```js run
 alert( 'S\u0307\u0323' ); // Ṩ, S + dot above + dot below
-alert( 'S\u0323\u0307' ); // Ṩ, S + dot below + dot above
+alert( 'S\u0323\u0307' ); // Ṩ, S + dot below + dot above
 
 alert( 'S\u0307\u0323' == 'S\u0323\u0307' ); // false
 ```
@@ -649,7 +653,7 @@ alert( "S\u0307\u0323".normalize().length ); // 1
 alert( "S\u0307\u0323".normalize() == "\u1e68" ); // true
 ```
 
-In reality, this is not always the case. The reason being that the symbol `Ṩ` is "common enough", so UTF-16 creators included it in the main table and gave it the code.
+In reality, this is not always the case. The reason being that the symbol `Ṩ` is "common enough", so UTF-16 creators included it in the main table and gave it the code.
 
 If you want to learn more about normalization rules and variants -- they are described in the appendix of the Unicode standard: [Unicode Normalization Forms](http://www.unicode.org/reports/tr15/), but for most practical purposes the information from this section is enough.
 

1-js/05-data-types/10-date/1-new-date/solution.md

@@ -1,4 +1,4 @@
-The `new Date` constructor uses the local time zone by default. So the only important thing to remember is that months start from zero.
+The `new Date` constructor uses the local time zone. So the only important thing to remember is that months start from zero.
 
 So February has number 1.
 

1-js/05-data-types/10-date/4-get-date-ago/task.md

@@ -8,7 +8,7 @@ Create a function `getDateAgo(date, days)` to return the day of month `days` ago
 
 For instance, if today is 20th, then `getDateAgo(new Date(), 1)` should be 19th and `getDateAgo(new Date(), 2)` should be 18th.
 
-Should also work over months/years reliably:
+Should work reliably for `days=365` or more:
 
 ```js
 let date = new Date(2015, 0, 2);

1-js/05-data-types/10-date/article.md

@@ -40,7 +40,7 @@ To create a new `Date` object call `new Date()` with one of the following argume
     ```js run
     let date = new Date("2017-01-26");
     alert(date);
-    // The time portion of the date is assumed to be midnight GMT and 
+    // The time is not set, so it's assumed to be midnight GMT and
     // is adjusted according to the timezone the code is run in
     // So the result could be
     // Thu Jan 26 2017 11:00:00 GMT+1100 (Australian Eastern Daylight Time)
@@ -51,8 +51,6 @@ To create a new `Date` object call `new Date()` with one of the following argume
 `new Date(year, month, date, hours, minutes, seconds, ms)`
 : Create the date with the given components in the local time zone. Only the first two arguments are obligatory.
 
-    Note:
-
     - The `year` must have 4 digits: `2013` is okay, `98` is not.
     - The `month` count starts with `0` (Jan), up to `11` (Dec).
     - The `date` parameter is actually the day of month, if absent then `1` is assumed.
@@ -74,7 +72,7 @@ To create a new `Date` object call `new Date()` with one of the following argume
 
 ## Access date components
 
-There are many methods to access the year, month and so on from the `Date` object. But they can be easily remembered when categorized.
+There are methods to access the year, month and so on from the `Date` object:
 
 [getFullYear()](mdn:js/Date/getFullYear)
 : Get the year (4 digits)
@@ -217,21 +215,21 @@ The important side effect: dates can be subtracted, the result is their differen
 That can be used for time measurements:
 
 ```js run
-let start = new Date(); // start counting
+let start = new Date(); // start measuring time
 
 // do the job
 for (let i = 0; i < 100000; i++) {
   let doSomething = i * i * i;
 }
 
-let end = new Date(); // done
+let end = new Date(); // end measuring time
 
 alert( `The loop took ${end - start} ms` );
 ```
 
 ## Date.now()
 
-If we only want to measure the difference, we don't need the `Date` object.
+If we only want to measure time, we don't need the `Date` object.
 
 There's a special method `Date.now()` that returns the current timestamp.
 
@@ -264,6 +262,8 @@ If we want a reliable benchmark of CPU-hungry function, we should be careful.
 
 For instance, let's measure two functions that calculate the difference between two dates: which one is faster?
 
+Such performance measurements are often called "benchmarks".
+
 ```js
 // we have date1 and date2, which function faster returns their difference in ms?
 function diffSubtract(date1, date2) {
@@ -280,7 +280,7 @@ These two do exactly the same thing, but one of them uses an explicit `date.getT
 
 So, which one is faster?
 
-The first idea may be to run them many times in a row and measure the time difference. For our case, functions are very simple, so we have to do it around 100000 times.
+The first idea may be to run them many times in a row and measure the time difference. For our case, functions are very simple, so we have to do it at least 100000 times.
 
 Let's measure:
 
@@ -310,7 +310,7 @@ Wow! Using `getTime()` is so much faster! That's because there's no type convers
 
 Okay, we have something. But that's not a good benchmark yet.
 
-Imagine that at the time of running `bench(diffSubtract)` CPU was doing something in parallel, and it was taking resources. And by the time of running `bench(diffGetTime)` the work has finished.
+Imagine that at the time of running `bench(diffSubtract)` CPU was doing something in parallel, and it was taking resources. And by the time of running `bench(diffGetTime)` that work has finished.
 
 A pretty real scenario for a modern multi-process OS.
 
@@ -368,7 +368,7 @@ for (let i = 0; i < 10; i++) {
 ```
 
 ```warn header="Be careful doing microbenchmarking"
-Modern JavaScript engines perform many optimizations. They may tweak results of "artificial tests" compared to "normal usage", especially when we benchmark something very small. So if you seriously want to understand performance, then please study how the JavaScript engine works. And then you probably won't need microbenchmarks at all.
+Modern JavaScript engines perform many optimizations. They may tweak results of "artificial tests" compared to "normal usage", especially when we benchmark something very small, such as how an operator works, or a built-in function. So if you seriously want to understand performance, then please study how the JavaScript engine works. And then you probably won't need microbenchmarks at all.
 
 The great pack of articles about V8 can be found at <http://mrale.ph>.
 ```
@@ -415,7 +415,7 @@ alert(date);
 
 Note that unlike many other systems, timestamps in JavaScript are in milliseconds, not in seconds.
 
-Also, sometimes we need more precise time measurements. JavaScript itself does not have a way to measure time in microseconds (1 millionth of a second), but most environments provide it. For instance, browser has [performance.now()](mdn:api/Performance/now) that gives the number of milliseconds from the start of page loading with microsecond precision (3 digits after the point):
+Sometimes we need more precise time measurements. JavaScript itself does not have a way to measure time in microseconds (1 millionth of a second), but most environments provide it. For instance, browser has [performance.now()](mdn:api/Performance/now) that gives the number of milliseconds from the start of page loading with microsecond precision (3 digits after the point):
 
 ```js run
 alert(`Loading started ${performance.now()}ms ago`);

1-js/09-classes/01-class/article.md

@@ -119,7 +119,7 @@ alert(Object.getOwnPropertyNames(User.prototype)); // constructor, sayHi
 
 ## Not just a syntax sugar
 
-Sometimes people say that `class` is a "syntax sugar" in JavaScript, because we could actually declare the same without `class` keyword at all:
+Sometimes people say that `class` is a "syntax sugar" (syntax that is designed to make things easier to read, but doesn't introduce anything new) in JavaScript, because we could actually declare the same without `class` keyword at all:
 
 ```js run
 // rewriting class User in pure functions

1-js/09-classes/03-static-properties-methods/article.md

@@ -17,10 +17,10 @@ class User {
 User.staticMethod(); // true
 ```
 
-That actually does the same as assigning it as a function property:
+That actually does the same as assigning it as a property:
 
 ```js
-function User() { }
+class User() { }
 
 User.staticMethod = function() {
   alert(this === User);