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

Author: iliakan

1-js/01-getting-started/1-intro/article.md

@@ -6,7 +6,7 @@ Let's see what's so special about JavaScript, what we can achieve with it, and w
 
 *JavaScript* was initially created to *"make web pages alive"*.
 
-The programs in this language are called *scripts*. They can be written right in a web page's HTML and executed automatically as the page loads.
+The programs in this language are called *scripts*. They can be written right in a web page's HTML and run automatically as the page loads.
 
 Scripts are provided and executed as plain text. They don't need special preparation or compilation to run.
 
@@ -70,7 +70,7 @@ Examples of such restrictions include:
     There are ways to interact with camera/microphone and other devices, but they require a user's explicit permission. So a JavaScript-enabled page may not sneakily enable a web-camera, observe the surroundings and send the information to the [NSA](https://en.wikipedia.org/wiki/National_Security_Agency).
 - Different tabs/windows generally do not know about each other. Sometimes they do, for example when one window uses JavaScript to open the other one. But even in this case, JavaScript from one page may not access the other if they come from different sites (from a different domain, protocol or port).
 
-    This is called the "Same Origin Policy". To work around that, *both pages* must contain a special JavaScript code that handles data exchange.
+    This is called the "Same Origin Policy". To work around that, *both pages* must agree for data exchange and contain a special JavaScript code that handles it. We'll cover that in the tutorial.
 
     This limitation is, again, for the user's safety. A page from `http://anysite.com` which a user has opened must not be able to access another browser tab with the URL `http://gmail.com` and steal information from there.
 - JavaScript can easily communicate over the net to the server where the current page came from. But its ability to receive data from other sites/domains is crippled. Though possible, it requires explicit agreement (expressed in HTTP headers) from the remote side. Once again, that's a safety limitation.

1-js/02-first-steps/04-variables/article.md

@@ -136,7 +136,7 @@ alert(message); // Hello world!
 ```
 
 ```smart header="Functional languages"
-It's interesting to note that [functional](https://en.wikipedia.org/wiki/Functional_programming) programming languages, like [Scala](http://www.scala-lang.org/) or [Erlang](http://www.erlang.org/), forbid changing variable values.
+It's interesting to note that there exist [functional](https://en.wikipedia.org/wiki/Functional_programming) programming languages, like [Scala](http://www.scala-lang.org/) or [Erlang](http://www.erlang.org/) that forbid changing variable values.
 
 In such languages, once the value is stored "in the box", it's there forever. If we need to store something else, the language forces us to create a new box (declare a new variable). We can't reuse the old one.
 
@@ -182,7 +182,7 @@ let my-name; // hyphens '-' aren't allowed in the name
 Variables named `apple` and `AppLE` are two different variables.
 ```
 
-````smart header="Non-English letters are allowed, but not recommended"
+````smart header="Non-Latin letters are allowed, but not recommended"
 It is possible to use any language, including cyrillic letters or even hieroglyphs, like this:
 
 ```js
@@ -254,7 +254,7 @@ There is a widespread practice to use constants as aliases for difficult-to-reme
 
 Such constants are named using capital letters and underscores.
 
-Like this:
+For instance, let's make constants for colors in so-called "web" (hexadecimal) format:
 
 ```js run
 const COLOR_RED = "#F00";
@@ -290,7 +290,7 @@ In other words, capital-named constants are only used as aliases for "hard-coded
 
 Talking about variables, there's one more extremely important thing.
 
-Please name your variables sensibly. Take time to think about this.
+A variable name should have a clean, obvious meaning, describe the data that it stores.
 
 Variable naming is one of the most important and complex skills in programming. A quick glance at variable names can reveal which code was written by a beginner versus an experienced developer.
 

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

@@ -226,7 +226,7 @@ The last three lines may need additional explanation:
 
 ## Summary
 
-There are 7 basic types in JavaScript.
+There are 7 basic data types in JavaScript.
 
 - `number` for numbers of any kind: integer or floating-point.
 - `string` for strings. A string may have one or more characters, there's no separate single-character type.

1-js/02-first-steps/09-alert-prompt-confirm/article.md

@@ -1,6 +1,6 @@
 # Interaction: alert, prompt, confirm
 
-This part of the tutorial aims to cover JavaScript "as is", without environment-specific tweaks.
+In this part of the tutorial we cover JavaScript language "as is", without environment-specific tweaks.
 
 But we'll still be using the browser as our demo environment, so we should know at least a few of its user-interface functions. In this chapter, we'll get familiar with the browser functions `alert`, `prompt` and `confirm`.
 

1-js/02-first-steps/10-ifelse/article.md

@@ -2,7 +2,7 @@
 
 Sometimes, we need to perform different actions based on different conditions.
 
-To do that, we use the `if` statement and the conditional (ternary) operator which we will be referring to as the “question mark” operator `?` for simplicity.
+To do that, we can use the `if` statement and the conditional operator `?`, that's also called a "question mark" operator.
 
 ## The "if" statement
 
@@ -103,7 +103,7 @@ In the code above, JavaScript first checks `year < 2015`. If that is falsy, it g
 
 There can be more `else if` blocks. The final `else` is optional.
 
-## Ternary operator '?'
+## Conditional operator '?'
 
 Sometimes, we need to assign a variable depending on a condition.
 
@@ -124,9 +124,9 @@ if (age > 18) {
 alert(accessAllowed);
 ```
 
-The so-called "ternary" or "question mark" operator lets us do that in a shorter and simpler way.
+The so-called "conditional" or "question mark" operator lets us do that in a shorter and simpler way.
 
-The operator is represented by a question mark `?`.  The formal term "ternary" means that the operator has three operands. It is actually the one and only operator in JavaScript which has that many.
+The operator is represented by a question mark `?`. Sometimes it's called "ternary", because the operator has three operands. It is actually the one and only operator in JavaScript which has that many.
 
 The syntax is:
 ```js
@@ -141,7 +141,7 @@ For example:
 let accessAllowed = (age > 18) ? true : false;
 ```
 
-Technically, we can omit the parentheses around `age > 18`. The question mark operator has a low precedence, so it executes after the comparison `>`. 
+Technically, we can omit the parentheses around `age > 18`. The question mark operator has a low precedence, so it executes after the comparison `>`.
 
 This example will do the same thing as the previous one:
 

1-js/02-first-steps/11-logical-operators/article.md

@@ -84,7 +84,7 @@ The OR `||` operator does the following:
 
 A value is returned in its original form, without the conversion.
 
-In other words, a chain of OR `"||"` returns the first truthy value or the last one if no such value is found.
+In other words, a chain of OR `"||"` returns the first truthy value or the last one if no truthy value is found.
 
 For instance:
 
@@ -101,7 +101,7 @@ This leads to some interesting usage compared to a "pure, classical, boolean-onl
 
 1. **Getting the first truthy value from a list of variables or expressions.**
 
-    Imagine we have several variables which can either contain data or be `null/undefined`. How can we find the first one with data?
+    Imagine we have a list of variables which can either contain data or be `null/undefined`. How can we find the first one with data?
 
     We can use OR `||`:
 
@@ -143,7 +143,7 @@ This leads to some interesting usage compared to a "pure, classical, boolean-onl
     alert(x); // 1
     ```
 
-    An assignment is a simple case. Other side effects can also be involved.
+    An assignment is a simple case. There may be side effects, that won't show up if the evaluation doesn't reach them.
 
     As we can see, such a use case is a "shorter way of doing `if`". The first operand is converted to boolean. If it's false, the second one is evaluated.
 

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

@@ -101,7 +101,7 @@ showMessage();
 alert( userName ); // *!*Bob*/!*, the value was modified by the function
 ```
 
-The outer variable is only used if there's no local one. So an occasional modification may happen if we forget `let`.
+The outer variable is only used if there's no local one.
 
 If a same-named variable is declared inside the function then it *shadows* the outer one. For instance, in the code below the function uses the local `userName`. The outer one is ignored:
 
@@ -128,7 +128,7 @@ Variables declared outside of any function, such as the outer `userName` in the
 
 Global variables are visible from any function (unless shadowed by locals).
 
-Usually, a function declares all variables specific to its task. Global variables only store project-level data, and it's important that these variables are accessible from anywhere. Modern code has few or no globals. Most variables reside in their functions.
+It's a good practice to minimize the use of global variables. Modern code has few or no globals. Most variables reside in their functions. Sometimes though, they can be useful to store project-level data.
 ```
 
 ## Parameters
@@ -376,7 +376,7 @@ A few examples of breaking this rule:
 - `createForm` -- would be bad if it modifies the document, adding a form to it (should only create it and return).
 - `checkPermission` -- would be bad if it displays the `access granted/denied` message (should only perform the check and return the result).
 
-These examples assume common meanings of prefixes. What they mean for you is determined by you and your team. Maybe it's pretty normal for your code to behave differently. But you should have a firm understanding of what a prefix means, what a prefixed function can and cannot do. All same-prefixed functions should obey the rules. And the team should share the knowledge.
+These examples assume common meanings of prefixes. You and your team are free to agree on other meanings, but usually they're not much different. In any case, you should have a firm understanding of what a prefix means, what a prefixed function can and cannot do. All same-prefixed functions should obey the rules. And the team should share the knowledge.
 ```
 
 ```smart header="Ultrashort function names"

1-js/02-first-steps/16-javascript-specials/article.md

@@ -103,7 +103,7 @@ More in: <info:variables> and <info:types>.
 We're using a browser as a working environment, so basic UI functions will be:
 
 [`prompt(question, [default])`](mdn:api/Window/prompt)
-: Ask a `question`, and return either what the visitor entered or `null` if they pressed "cancel".
+: Ask a `question`, and return either what the visitor entered or `null` if they clicked "cancel".
 
 [`confirm(question)`](mdn:api/Window/confirm)
 : Ask a `question` and suggest to choose between Ok and Cancel. The choice is returned as `true/false`.
@@ -161,7 +161,7 @@ Comparisons
 
     Other comparisons convert to a number as well.
 
-    The strict equality operator `===` doesn't do the conversion: different types always mean different values for it, so:
+    The strict equality operator `===` doesn't do the conversion: different types always mean different values for it.
 
     Values `null` and `undefined` are special: they equal `==` each other and don't equal anything else.
 

1-js/03-code-quality/01-debugging-chrome/article.md

@@ -20,7 +20,7 @@ Here's what you should see if you are doing it for the first time:
 
 The toggler button <span class="devtools" style="background-position:-168px -76px"></span> opens the tab with files.
 
-Let's click it and select `index.html` and then `hello.js` in the tree view. Here's what should show up:
+Let's click it and select `hello.js` in the tree view. Here's what should show up:
 
 ![](chrome-tabs.png)
 
@@ -34,7 +34,7 @@ Now you could click the same toggler <span class="devtools" style="background-po
 
 ## Console
 
-If we press `Esc`, then a console opens below. We can type commands there and press `key:Enter` to execute.
+If we press `key:Esc`, then a console opens below. We can type commands there and press `key:Enter` to execute.
 
 After a statement is executed, its result is shown below.
 

1-js/03-code-quality/06-polyfills/article.md

@@ -19,21 +19,20 @@ Here Babel comes to the rescue.
 
 Actually, there are two parts in Babel:
 
-1. First, the transpiler program, which rewrites the code. The developer runs it on their own computer. It rewrites the code into the older standard. And then the code is delivered to the website for users. Modern project build system like [webpack](http://webpack.github.io/) or [brunch](http://brunch.io/) provide means to run transpiler automatically on every code change, so that doesn't involve any time loss from our side.
+1. First, the transpiler program, which rewrites the code. The developer runs it on their own computer. It rewrites the code into the older standard. And then the code is delivered to the website for users. Modern project build system like [webpack](http://webpack.github.io/) provide means to run transpiler automatically on every code change, so that very easy to integrate into development process.
 
 2. Second, the polyfill.
 
-    The transpiler rewrites the code, so syntax features are covered. But for new functions we need to write a special script that implements them. JavaScript is a highly dynamic language, scripts may not just add new functions, but also modify built-in ones, so that they behave according to the modern standard.
+    New language features may include new built-in functions and syntax constructs.
+    The transpiler rewrites the code, transforming syntax constructs into older ones. But as for new built-in functions, we need to implement them. JavaScript is a highly dynamic language, scripts may add/modify any functions, so that they behave according to the modern standard.
 
-    There's a term "polyfill" for scripts that "fill in" the gap and add missing implementations.
+    A script that updates/adds new functions is called "polyfill". It "fills in" the gap and adds missing implementations.
 
     Two interesting polyfills are:
     - [babel polyfill](https://babeljs.io/docs/usage/polyfill/) that supports a lot, but is big.
     - [polyfill.io](http://polyfill.io) service that allows to load/construct polyfills on-demand, depending on the features we need.
 
-So, we need to setup the transpiler and add the polyfill for old engines to support modern features.
-
-If we orient towards modern engines and do not use features except those supported everywhere, then we don't need to use Babel.
+So, if we're going to use modern language features, a transpiler and a polyfill are necessary.
 
 ## Examples in the tutorial
 
@@ -49,9 +48,7 @@ Examples that use modern JS will work only if your browser supports it.
 ````
 
 ```offline
-As you're reading the offline version, examples are not runnable. But they usually work :)
+As you're reading the offline version, in PDF examples are not runnable. In EPUB some of them can run.
 ```
 
-[Chrome Canary](https://www.google.com/chrome/browser/canary.html) is good for all examples, but other modern browsers are mostly fine too.
-
-Note that on production we can use Babel to translate the code into suitable for less recent browsers, so there will be no such limitation, the code will run everywhere.
+Google Chrome is usually the most up-to-date with language features, good to run bleeding-edge demos without any transpilers, but other modern browsers also work fine.

1-js/04-object-basics/06-constructor-new/article.md

@@ -83,7 +83,7 @@ let user = new function() {
 The constructor can't be called again, because it is not saved anywhere, just created and called. So this trick aims to encapsulate the code that constructs the single object, without future reuse.
 ````
 
-## Dual-syntax constructors: new.target
+## Constructor mode test: new.target
 
 ```smart header="Advanced stuff"
 The syntax from this section is rarely used, skip it unless you want to know everything.
@@ -109,7 +109,9 @@ new User(); // function User { ... }
 */!*
 ```
 
-That can be used to allow both `new` and regular calls to work the same. That is, create the same object:
+That can be used inside the function to know whether it was called with `new`, "in constructor mode", or without it, "in regular mode".
+
+We can also make both `new` and regular calls to do the same, like this:
 
 ```js run
 function User(name) {

1-js/05-data-types/01-primitives-methods/1-string-new-property/solution.md

@@ -6,26 +6,21 @@ let str = "Hello";
 
 str.test = 5; // (*)
 
-alert(str.test); 
+alert(str.test);
 ```
 
-There may be two kinds of result:
-1. `undefined`
-2. An error.
+Depending on whether you have `use strict` or not, the result may be:
+1. `undefined` (no strict mode)
+2. An error (strict mode).
 
 Why? Let's replay what's happening at line `(*)`:
 
 1. When a property of `str` is accessed, a "wrapper object" is created.
-2. The operation with the property is carried out on it. So, the object gets the `test` property.
-3. The operation finishes and the "wrapper object" disappears.
+2. In strict mode, writing into it is an error.
+3. Otherwise, the operation with the property is carried on, the object gets the `test` property, but after that the "wrapper object" disappears.
 
-So, on the last line, `str` has no trace of the property. A new wrapper object for every object operation on a string.
-
-Some browsers though may decide to further limit the programmer and disallow to assign properties to primitives at all. That's why in practice we can also see errors at line `(*)`. It's a little bit farther from the specification though.
+So, without strict mode, in the last line `str` has no trace of the property.
 
 **This example clearly shows that primitives are not objects.**
 
-They just can not store data. 
-
-All property/method operations are performed with the help of temporary objects.
-
+They can't store additional data.

1-js/05-data-types/01-primitives-methods/article.md

@@ -14,7 +14,7 @@ A primitive
 An object
 
 - Is capable of storing multiple values as properties.
-- Can be created with `{}`, for instance: `{name: "John", age: 30}`. There are other kinds of objects in JavaScript; functions, for example, are objects.
+- Can be created with `{}`, for instance: `{name: "John", age: 30}`. There are other kinds of objects in JavaScript: functions, for example, are objects.
 
 One of the best things about objects is that we can store a function as one of its properties.
 
@@ -48,7 +48,7 @@ The solution looks a little bit awkward, but here it is:
 
 1. Primitives are still primitive. A single value, as desired.
 2. The language allows access to methods and properties of strings, numbers, booleans and symbols.
-3. When this happens, a special "object wrapper" that provides the extra functionality is created, and then is destroyed.
+3. In order for that to work, a special "object wrapper" that provides the extra functionality is created, and then is destroyed.
 
 The "object wrappers" are different for each primitive type and are called: `String`, `Number`, `Boolean` and `Symbol`. Thus, they provide different sets of methods.
 
@@ -91,18 +91,18 @@ In JavaScript, that's also possible for historical reasons, but highly **unrecom
 For instance:
 
 ```js run
-alert( typeof 1 ); // "number"
+alert( typeof 0 ); // "number"
 
-alert( typeof new Number(1) ); // "object"!
+alert( typeof new Number(0) ); // "object"!
 ```
 
-And because what follows, `zero`, is an object, the alert will show up:
+Objects are always truthy in `if`, so here the alert will show up:
 
 ```js run
 let zero = new Number(0);
 
 if (zero) { // zero is true, because it's an object
-  alert( "zero is truthy?!?" );
+  alert( "zero is truthy!?!" );
 }
 ```