Resolve conflicts/Update files

Author: odsantos

1-js/02-first-steps/04-variables/2-declare-variables/solution.md

@@ -1,25 +1,21 @@
-Primeiro, a variável para o nome do nosso planeta.
+## A variável para o nosso planeta
 
 Isso é simples:
 
 ```js
 let ourPlanetName = "Earth";
 ```
 
-<<<<<<< HEAD
-Note que poderíamos usar um nome mais curto, `planet`, mas pode não ser óbvio a que planeta se refere. É bom ser mais detalhado. Pelo menos até a variável isNotTooLong.
-=======
-Note, we could use a shorter name `planet`, but it might not be obvious what planet it refers to. It's nice to be more verbose. At least until the variable isNotTooLong.
->>>>>>> c56e6a57ac3497aab77128c5bfca13513980709b
+Note que poderíamos usar um nome mais curto, `planet`, mas pode não ser óbvio a que planeta se refere. É bom ser mais detalhado. Pelo menos até a variável naoForDemasiadoLonga.
 
-Em segundo lugar, o nome do visitante atual:
+## O nome do visitante atual
 
 ```js
 let currentUserName = "John";
 ```
 
-Novamente, nós poderíamos encurtar isso para `userName` se tivermos certeza que o usuário é atual.
+Novamente, nós poderíamos encurtar isso para `userName` se tivermos a certeza de que o usuário é o atual.
 
 Os editores modernos e o autocomplete facilitam a escrita de nomes longos de variáveis. Não salve neles. Um nome com 3 palavras é o suficiente.
 
-E se o seu editor não possui autocompletar corretamente, obtenha [um novo](/code-editors).
+E se o seu editor não possui autocompletar corretamente, obtenha [um novo](/code-editors).

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

@@ -26,17 +26,6 @@ A [transpiler](https://en.wikipedia.org/wiki/Source-to-source_compiler) is a spe
 
 E.g. JavaScript before year 2020 didn't have the "nullish coalescing operator" `??`. So, if a visitor uses an outdated browser, it may fail to understand the code like `height = height ?? 100`.
 
-<<<<<<< HEAD
-    There's a term "polyfill" for scripts that "fill in" the gap and add 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.
-=======
 A transpiler would analyze our code and rewrite `height ?? 100` into `(height !== undefined && height !== null) ? height : 100`.
 
 ```js
@@ -46,7 +35,6 @@ height = height ?? 100;
 // after running the transpiler
 height = (height !== undefined && height !== null) ? height : 100;
 ```
->>>>>>> c56e6a57ac3497aab77128c5bfca13513980709b
 
 Now the rewritten code is suitable for older JavaScript engines.
 
@@ -64,15 +52,6 @@ For example, `Math.trunc(n)` is a function that "cuts off" the decimal part of a
 
 In some (very outdated) JavaScript engines, there's no `Math.trunc`, so such code will fail.
 
-<<<<<<< HEAD
-```offline
-As you're reading the offline version, examples are not runnable. But they usually work :)
-```
-
-[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.
-=======
 As we're talking about new functions, not syntax changes, there's no need to transpile anything here. We just need to declare the missing function.
 
 A script that updates/adds new functions is called "polyfill". It "fills in" the gap and adds missing implementations.
@@ -111,4 +90,3 @@ Good resources that show the current state of support for various features:
 
 P.S. Google Chrome is usually the most up-to-date with language features, try it if a tutorial demo fails. Most tutorial demos work with any modern browser though.
 
->>>>>>> c56e6a57ac3497aab77128c5bfca13513980709b

1-js/05-data-types/04-array/article.md

@@ -1,12 +1,12 @@
-# Arrays 
+# Arrays
 
 Objects allow you to store keyed collections of values. That's fine.
 
-But quite often we find that we need an *ordered collection*, where we have a 1st, a 2nd, a 3rd element and so on. For example, we need that to store a list of something: users, goods, HTML elements etc. 
+But quite often we find that we need an *ordered collection*, where we have a 1st, a 2nd, a 3rd element and so on. For example, we need that to store a list of something: users, goods, HTML elements etc.
 
 It is not convenient to use an object here, because it provides no methods to manage the order of elements. We can’t insert a new property “between” the existing ones. Objects are just not meant for such use.
 
-There exists a special data structure named `Array`, to store ordered collections. 
+There exists a special data structure named `Array`, to store ordered collections.
 
 ## Declaration
 
@@ -81,10 +81,10 @@ arr[3](); // hello
 
 ````smart header="Trailing comma"
 An array, just like an object, may end with a comma:
-```js 
+```js
 let fruits = [
-  "Apple", 
-  "Orange", 
+  "Apple",
+  "Orange",
   "Plum"*!*,*/!*
 ];
 ```
@@ -95,7 +95,7 @@ The "trailing comma" style makes it easier to insert/remove items, because all l
 
 ## Methods pop/push, shift/unshift
 
-A [queue](https://en.wikipedia.org/wiki/Queue_(abstract_data_type)) is one of most common uses of an array. In computer science, this means an ordered collection of elements which supports two operations:
+A [queue](https://en.wikipedia.org/wiki/Queue_(abstract_data_type)) is one of the most common uses of an array. In computer science, this means an ordered collection of elements which supports two operations:
 
 - `push` appends an element to the end.
 - `shift` get an element from the beginning, advancing the queue, so that the 2nd element becomes the 1st.
@@ -106,7 +106,7 @@ Arrays support both operations.
 
 In practice we need it very often. For example, a queue of messages that need to be shown on-screen.
 
-There's another use case for arrays -- the data structure named [stack](https://en.wikipedia.org/wiki/Stack_(abstract_data_type)). 
+There's another use case for arrays -- the data structure named [stack](https://en.wikipedia.org/wiki/Stack_(abstract_data_type)).
 
 It supports two operations:
 
@@ -121,7 +121,7 @@ A stack is usually illustrated as a pack of cards: new cards are added to the to
 
 For stacks, the latest pushed item is received first, that's also called LIFO (Last-In-First-Out) principle. For queues, we have FIFO (First-In-First-Out).
 
-Arrays in JavaScript can work both as a queue and as a stack. They allow you to add/remove elements both to/from the beginning or the end. 
+Arrays in JavaScript can work both as a queue and as a stack. They allow you to add/remove elements both to/from the beginning or the end.
 
 In computer science the data structure that allows this, is called [deque](https://en.wikipedia.org/wiki/Double-ended_queue).
 
@@ -189,7 +189,7 @@ alert( fruits );
 
 ## Internals
 
-An array is a special kind of object. The square brackets used to access a property `arr[0]` actually come from the object syntax. Numbers are used as keys. 
+An array is a special kind of object. The square brackets used to access a property `arr[0]` actually come from the object syntax. That's essentially the same as `obj[key]`, where `arr` is the object, while numbers are used as keys.
 
 They extend objects providing special methods to work with ordered collections of data and also the `length` property. But at the core it's still an object.
 
@@ -203,7 +203,7 @@ let fruits = ["Banana"]
 let arr = fruits; // copy by reference (two variables reference the same array)
 
 alert( arr === fruits ); // true
- 
+
 arr.push("Pear"); // modify the array by reference
 
 alert( fruits ); // Banana, Pear - 2 items now
@@ -229,7 +229,7 @@ But the engine will see that we're working with the array as with a regular obje
 
 The ways to misuse an array:
 
-- Add a non-numeric property like `arr.test = 5`. 
+- Add a non-numeric property like `arr.test = 5`.
 - Make holes, like: add `arr[0]` and then `arr[1000]` (and nothing between them).
 - Fill the array in the reverse order, like `arr[1000]`, `arr[999]` and so on.
 
@@ -296,7 +296,7 @@ let fruits = ["Apple", "Orange", "Plum"];
 
 // iterates over array elements
 for (let fruit of fruits) {
-  alert( fruit ); 
+  alert( fruit );
 }
 ```
 
@@ -320,7 +320,7 @@ But that's actually a bad idea. There are potential problems with it:
 
     There are so-called "array-like" objects in the browser and in other environments, that *look like arrays*. That is, they have `length` and indexes properties, but they may also have other non-numeric properties and methods, which we usually don't need. The `for..in` loop will list them though. So if we need to work with array-like objects, then these "extra" properties can become a problem.
 
-2. The `for..in` loop is optimized for generic objects, not arrays, and thus is 10-100 times slower. Of course, it's still very fast. The speedup may only matter in bottlenecks or seem irrelevant. But still we should be aware of the difference.
+2. The `for..in` loop is optimized for generic objects, not arrays, and thus is 10-100 times slower. Of course, it's still very fast. The speedup may only matter in bottlenecks. But still we should be aware of the difference.
 
 Generally, we shouldn't use `for..in` for arrays.
 
@@ -338,7 +338,7 @@ fruits[123] = "Apple";
 alert( fruits.length ); // 124
 ```
 
-Note that we usually don't use arrays like that. 
+Note that we usually don't use arrays like that.
 
 Another interesting thing about the `length` property is that it's writable.
 
@@ -385,7 +385,7 @@ To evade such surprises, we usually use square brackets, unless we really know w
 
 ## Multidimensional arrays
 
-Arrays can have items that are also arrays. We can use it for multidimensional arrays, to store matrices:
+Arrays can have items that are also arrays. We can use it for multidimensional arrays, for example to store matrices:
 
 ```js run
 let matrix = [
@@ -394,7 +394,7 @@ let matrix = [
   [7, 8, 9]
 ];
 
-alert( matrix[1][1] ); // the central element
+alert( matrix[1][1] ); // 5, the central element
 ```
 
 ## toString
@@ -492,15 +492,15 @@ Array is a special kind of object, suited to storing and managing ordered data i
 
     The call to `new Array(number)` creates an array with the given length, but without elements.
 
-- The `length` property is the array length or, to be precise, its last numeric index plus one. It is auto-adjusted by array methods. 
+- The `length` property is the array length or, to be precise, its last numeric index plus one. It is auto-adjusted by array methods.
 - If we shorten `length` manually, the array is truncated.
 
 We can use an array as a deque with the following operations:
 
 - `push(...items)` adds `items` to the end.
 - `pop()` removes the element from the end and returns it.
 - `shift()` removes the element from the beginning and returns it.
-- `unshift(...items)` adds items to the beginning.
+- `unshift(...items)` adds `items` to the beginning.
 
 To loop over the elements of the array:
   - `for (let i=0; i<arr.length; i++)` -- works fastest, old-browser-compatible.

1-js/09-classes/04-private-protected-properties-methods/article.md

@@ -48,16 +48,16 @@ So, all we need to use an object is to know its external interface. We may be co
 
 That was a general introduction.
 
-In JavaScript, there are three types of properties and members:
+In JavaScript, there are two types of object fields (properties and methods):
 
 - Public: accessible from anywhere. They comprise the external interface. Until now we were only using public properties and methods.
 - Private: accessible only from inside the class. These are for the internal interface.
 
-In many other languages there also exist "protected" fields: accessible only from inside the class and those extending it. They are also useful for the internal interface. They are in a sense more widespread than private ones, because we usually want inheriting classes to gain access to properly do the extension.
+In many other languages there also exist "protected" fields: accessible only from inside the class and those extending it (like private, but plus access from inheriting classes). They are also useful for the internal interface. They are in a sense more widespread than private ones, because we usually want inheriting classes to gain access to them.
 
 Protected fields are not implemented in JavaScript on the language level, but in practice they are very convenient, so they are emulated.
 
-In the next step we'll make a coffee machine in JavaScript with all these types of properties. A coffee machine has a lot of details, we won't model them to stay simple (though we could).
+Now we'll make a coffee machine in JavaScript with all these types of properties. A coffee machine has a lot of details, we won't model them to stay simple (though we could).
 
 ## Protecting "waterAmount"
 
@@ -87,7 +87,7 @@ Let's change `waterAmount` property to protected to have more control over it. F
 
 **Protected properties are usually prefixed with an underscore `_`.**
 
-That is not enforced on the language level, but there's a convention that such properties and methods should not be accessed from the outside. Most programmers follow it.
+That is not enforced on the language level, but there's a well-known convention between programmers that such properties and methods should not be accessed from the outside.
 
 So our property will be called `_waterAmount`:
 
@@ -166,16 +166,16 @@ class CoffeeMachine {
   }
 
   *!*getWaterAmount()*/!* {
-    return this.waterAmount;
+    return this._waterAmount;
   }
 }
 
 new CoffeeMachine().setWaterAmount(100);
 ```
 
-That looks a bit longer, but functions are more flexible. They can accept multiple arguments (even if we don't need them right now). So, for the future, just in case we need to refactor something, functions are a safer choise.
+That looks a bit longer, but functions are more flexible. They can accept multiple arguments (even if we don't need them right now).
 
-Surely, there's a tradeoff. On the other hand, get/set syntax is shorter, so ultimately there's no strict rule, it's up to you to decide.
+On the other hand, get/set syntax is shorter, so ultimately there's no strict rule, it's up to you to decide.
 ````
 
 ```smart header="Protected fields are inherited"
@@ -192,9 +192,9 @@ There's a finished JavaScript proposal, almost in the standard, that provides la
 
 Privates should start with `#`. They are only accessible from inside the class.
 
-For instance, here we add a private `#waterLimit` property and extract the water-checking logic into a separate method:
+For instance, here's a private `#waterLimit` property and the water-checking private method `#checkWater`:
 
-```js
+```js run
 class CoffeeMachine {
 *!*
   #waterLimit = 200;
@@ -207,39 +207,19 @@ class CoffeeMachine {
   }
 */!*
 
-<<<<<<< HEAD
-  _waterAmount = 0;
-
-  set waterAmount(value) {
-*!*
-    this.#checkWater(value);
-*/!*
-    this._waterAmount = value;
-  }
-
-  get waterAmount() {
-    return this.waterAmount;
-=======
   setWaterAmount(value) {
     this.#waterLimit = this.#fixWaterAmount(value);
->>>>>>> c56e6a57ac3497aab77128c5bfca13513980709b
   }
 
 }
 
 let coffeeMachine = new CoffeeMachine();
 
 *!*
-<<<<<<< HEAD
-coffeeMachine.#checkWater(); // Error
-=======
 // can't access privates from outside of the class
 coffeeMachine.#fixWaterAmount(123); // Error
->>>>>>> c56e6a57ac3497aab77128c5bfca13513980709b
 coffeeMachine.#waterLimit = 1000; // Error
 */!*
-
-coffeeMachine.waterAmount = 100; // Works
 ```
 
 On the language level, `#` is a special sign that the field is private. We can't access it from outside or from inheriting classes.
@@ -285,17 +265,17 @@ class MegaCoffeeMachine extends CoffeeMachine {
 
 In many scenarios such limitation is too severe. If we extend a `CoffeeMachine`, we may have legitimate reasons to access its internals. That's why protected fields are used more often, even though they are not supported by the language syntax.
 
-````warn
+````warn header="Private fields are not available as this[name]"
 Private fields are special.
 
-Remember, usually we can access fields by this[name]:
+As we know, usually we can access fields using `this[name]`:
 
 ```js
 class User {
   ...
   sayHi() {
     let fieldName = "name";
-    alert(`Hello, ${this[fieldName]}`);
+    alert(`Hello, ${*!*this[fieldName]*/!*}`);
   }
 }
 ```
@@ -321,11 +301,11 @@ Protection for users, so that they don't shoot themselves in the foot
 Supportable
 : The situation in programming is more complex than with a real-life coffee machine, because we don't just buy it once. The code constantly undergoes development and improvement.
 
-    **If we strictly delimit the internal interface, then the developer of the class can freely change its internal properties and methods, even without informing the users..**
+    **If we strictly delimit the internal interface, then the developer of the class can freely change its internal properties and methods, even without informing the users.**
 
-    It's much easier to develop, if you know that certain methods can be renamed, their parameters can be changed, and even removed, because no external code depends on them.
+    If you're a developer of such class, it's great to know that private methods can be safely renamed, their parameters can be changed, and even removed, because no external code depends on them.
 
-    For users, when a new version comes out, it may be a total overhaul, but still simple to upgrade if the external interface is the same.
+    For users, when a new version comes out, it may be a total overhaul internally, but still simple to upgrade if the external interface is the same.
 
 Hiding complexity
 : People adore using things that are simple. At least from outside. What's inside is a different thing.