Merge branch 'ru-translation' of https://github.com/shamansir/JavaScript-Garden into russian-translation

Author: ZhangYiJiang

.gitignore

@@ -2,3 +2,6 @@
 /build
 /html
 /site/de
+/site/ru
+*.md~
+*.src.md

doc/language.json

@@ -1,4 +1,5 @@
 {
     "default": "en",
-    "listed": ["en"]
+    "listed": ["en", "ru"]
 }
+

doc/ru/appendix/fromtranslators.md

@@ -0,0 +1,14 @@
+## От переводчиков
+
+Авторы этой документации требуют от читателя не совершать каких-либо ошибок и постоянно следить за качеством пишущегося кода. Мы, как переводчики и опытные программисты на JavaScript рекомендуем *прислушиваться* к этим советам, но при этом не делать из этого *крайность*. Опыт — сын ошибок трудных, и иногда в борьбе с ошибками зарождается намного более детальное понимание предмета. Да, нужно избегать ошибок, но допускать их неосознанно — вполне нормально.
+
+К примеру, в статье про [сравнение объектов](#types.equality) авторы настоятельно рекомендуют использовать *только* оператор строгого неравенства `===`. Но мы считаем, что если вы уверены и осознали, что оба сравниваемых операнда имеют один тип, вы имеете право опустить последний символ `=`. Вы вольны применять строгое неравенство только в случаях, когда вы не уверены в типах операндов (`!== undefined` — это полезный приём). Так в вашем коде будут опасные и безопасные области, но при этом по коду будет явно видно, где вы рассчитываете на переменные одинаковых типов, а где позволяете пользователю вольности.
+
+Функцию [`setInterval`](#other.timeouts) тоже можно использовать, если вы стопроцентно уверены, что код внутри неё будет исполняться как минимум в три раза быстрее переданного ей интервала.
+
+С другой стороны, [использование `var`](#function.scopes) и грамотная [расстановка точек с запятой](#core.semicolon) — обязательные вещи, халатное отношение к которым никак не может быть оправдано — в осознанном пропуске `var` (если только вы не переопределяете глобальный объект браузера... хотя *зачем*?) или точки с запятой нет никакого смысла.
+
+Относитесь с **мудростью** к тому, что вы пишете — *важно* знать как работает именно ваш код и как это соответствует приведённым в статье тезисам — и уже из этого вы сможете делать вывод, подходит ли вам тот или иной подход или нет. *Важно* знать как работает [прототипное наследование](#object.prototype), но это не так необходимо, если вы используете функциональный подход или пользуетесь какой-либо сторонней библиотекой. Важно помнить о том, что у вас недостаёт какого-либо конкретного знания и что пробел следует заполнить, но если вы не используете в работе эту часть, вы всё равно можете писать хороший код — ну, если у вас есть талант.
+
+Гонка за оптимизацией — это драматично и правильно, но лучше написать работающий и понятный вам код, а потом уже его оптимизировать и искать узкие места, при необходимости. Оптимизацию необходимо делать, если вы видите явные неудобства для пользователя в тех или иных браузерах или у вас есть супер-крупный проект, которым никогда мешает оптимизация, или вы работаете с какой-либо сверхтребовательной технологией типа WebGL. Данная документация очень поможет вам в определении этих узких мест.
+

doc/ru/array/constructor.md

@@ -0,0 +1,25 @@
+## Конструктор `Array`
+
+Так как в конструкторе `Array` есть некоторая двусмысленность касающаяся его параметров, настоятельно рекомендуется при создании массивов всегда использовать синтаксис литеральной нотации — `[]`.
+
+    [1, 2, 3]; // Результат: [1, 2, 3]
+    new Array(1, 2, 3); // Результат: [1, 2, 3]
+
+    [3]; // Результат: [3]
+    new Array(3); // Результат: []
+    new Array('3') // Результат: ['3']
+
+В случае, когда в конструктор `Array` передаётся один аргумент и этот аргумент имеет тип `Number`, конструктор возвращает новый, *заполненный случайными значениями*, массив, имеющий длину равную значению переданного аргумента. Стоит заметить, что в этом случае будет установлено только свойство `length` нового массива, индексы массива фактически не будут проинициализированы.
+
+    var arr = new Array(3);
+    arr[1]; // не определён, undefined
+    1 in arr; // false, индекс не был установлен
+
+Поведение, которое позволяет изначально установить только размер массива может пригодиться лишь в нескольких случаях, таких как повторение строк, за счёт чего избегается использование цикла `for loop`.
+
+    new Array(count + 1).join(stringToRepeat);
+
+### Заключение
+
+Использование конструктора `Array` нужно избегать, насколько это возможно. Литералы определённо предпочтительнее — это краткая запись и она имеет более понятный синтаксис, так что при этом даже улучшается читабельность кода.
+

doc/ru/array/general.md

@@ -0,0 +1,40 @@
+##  Итерации по массивам и свойства
+
+Несмотря на то, что массивы в JavaScript являются объектами, нет достаточных оснований для использования [цикла `for in`](#object.forinloop) для итерации по элементам массива. Фактически, существует несколько весомых причин **против** использования `for in` в массивах.
+
+> **Замечание:** Массивы в JavaScript **не** являются *ассоциативными массивами*. Для связывания ключей и значений в JavaScript есть только [объекты](#object.general). И при том, что ассоциативные массивы **сохраняют** заданный порядок, объекты **не** делают этого.
+
+Во время выполнения `for in` циклически перебираются все свойства объекта, находящиеся в цепочке прототипов. Единственный способ исключить ненужные свойства — использовать [`hasOwnProperty`](#object.hasownproperty), а это **в 20 раз** медленнее обычного цикла `for`.
+
+### Итерирование
+
+Для достижения лучшей производительности при итерации по массивам, лучше всего использовать обычный цикл `for`.
+
+    var list = [1, 2, 3, 4, 5, ...... 100000000];
+    for(var i = 0, l = list.length; i < l; i++) {
+        console.log(list[i]);
+    }
+
+В примере выше есть один дополнительный приём, с помощью которого кэшируется величина длины массива: `l = list.length`.
+
+Несмотря на то, что свойство `length` определено в самом массиве, поиск этого свойства накладывает дополнительные расходы на каждой итерации цикла. Пусть в этом случае новые движки JavaScript теоретически **могут** применить оптимизацию, но нет никакого способа узнать, будет оптимизирован код на новом движке или нет.
+
+Фактически, отсутствие кэширования может привести к выполнению цикла в **два раза медленнее**, чем при кэшировании длины
+
+### Свойство `length`
+
+Хотя *геттер* свойства `length` просто возвращает количество элементов содежащихся в массиве, *сеттер* можно использовать для **обрезания** массива.
+
+    var foo = [1, 2, 3, 4, 5, 6];
+    foo.length = 3;
+    foo; // [1, 2, 3]
+
+    foo.length = 6;
+    foo; // [1, 2, 3]
+
+Присвоение свойству `length` меньшей величины урезает массив, однако присвоение большего значения не даст никакого эффекта.
+
+### Заключение
+
+Для оптимальной работы кода рекомендуется всегда использовать простой цикл `for` и кэшировать свойство `length`. Использование `for in` с массивами является признаком плохого кода, обладающего предпосылками к ошибкам и может привести к низкой скорости его выполнения.
+

doc/ru/core/eval.md

@@ -0,0 +1,39 @@
+## Почему нельзя использовать `eval`
+
+Функция `eval` выполняет строку кода JavaScript в локальной области видимости.
+
+    var foo = 1;
+    function test() {
+        var foo = 2;
+        eval('foo = 3');
+        return foo;
+    }
+    test(); // 3
+    foo; // 1
+
+Но `eval` исполняется в локальной области видимости только тогда, когда он вызывается **напрямую** *и при этом* имя вызываемой функции именно `eval`.
+
+    var foo = 1;
+    function test() {
+        var foo = 2;
+        var bar = eval;
+        bar('foo = 3');
+        return foo;
+    }
+    test(); // 2
+    foo; // 3
+
+**Любой ценой** избегайте использования функции `eval`. 99.9% случаев её "использования" могут достигаться **без её участия**.
+
+### `eval` под прикрытием
+
+Обе [функции работы с интервалами времени](#other.timeouts) `setTimeout` и `setInterval` могут принимать строку в качестве первого аргумента. Эта строка **всегда** будет выполняться в глобальной области видимости, поскольку `eval` в этом случае вызывается *не напрямую*.
+
+### Проблемы с безопасностью
+
+Кроме всего прочего, функция `eval` — это проблема в безопасности, поскольку исполняется **любой** переданный в неё код; **никогда** не следует использовать её со строками из неизвестных или недоверительных источников.
+
+### Заключение
+
+Никогда не стоит использовать `eval`: любое применение такого кода поднимает вопросы о качестве его работы, производительности и безопасности. Если вдруг для работы вам необходим `eval`, эта часть должна тут же ставиться под сомнение и **не** должна использоваться в первую очередь — необходимо найти *лучший способ* , которому не требуются вызовы `eval`.
+

doc/ru/core/semicolon.md

@@ -0,0 +1,100 @@
+## Автоматическая вставка точек с запятой
+
+Хоть JavaScript и имеет синтаксис, подобный языкам семейства C, он при этом **не** принуждает вас ставить точки с запятой в исходном коде — вы всегда можете их опустить.
+
+При этом JavaScript — не язык без точек с запятой, они на самом деле нужны ему, чтобы он мог разобраться в вашем коде. Поэтому парсер JavaScript **автоматически** вставляет их в те места, где сталкивается с ошибкой парсинга из-за их отсутствия.
+
+    var foo = function() {
+    } // ошибка разбора, ожидается точка с запятой
+    test()
+
+Происходит вставка и парсер пытается снова.
+
+    var foo = function() {
+    }; // ошибки нет, парсер продолжает
+    test()
+
+Автоматическая вставка точек с запятой считается одним из **наибольших** упущений в проекте языка, поскольку она *может* изменить поведение кода.
+
+### Как это работает
+
+Приведённый код не содержит точек с запятой, так что места для их вставки остаются на совести парсера:
+
+    (function(window, undefined) {
+        function test(options) {
+            log('тестируем!')
+
+            (options.list || []).forEach(function(i) {
+
+            })
+
+            options.value.test(
+                'здесь передадим длинную строчку',
+                'и ещё одну на всякий случай'
+            )
+
+            return
+            {
+                foo: function() {}
+            }
+        }
+        window.test = test
+
+    })(window)
+
+    (function(window) {
+        window.someLibrary = {}
+
+    })(window)
+
+Ниже представлен результат игры парсера в "угадалки".
+
+    (function(window, undefined) {
+        function test(options) {
+
+            // не вставлена точка с запятой, строки были объединены
+            log('тестируем!')(options.list || []).forEach(function(i) {
+
+            }); // <- вставлена
+
+            options.value.test(
+                'здесь передадим длинную строчку',
+                'и ещё одну на всякий случай'
+            ); // <- вставлена
+
+            return; // <- вставлена, в результате оператор return разбит на два блока
+            { // теперь парсер считает этот блок отдельным
+
+                // метка и одинокое выражение
+                foo: function() {}
+            }; // <- вставлена
+        }
+        window.test = test; // <- вставлена
+
+    // снова объединились строки
+    })(window)(function(window) {
+        window.someLibrary = {}; // <- вставлена
+
+    })(window); //<- вставлена
+
+> **Замечание:** Парсер JavaScript некорректно обрабатывает оператор `return`, за которым следует новая строка; кстати, причина может быть и не в автоматической вставке точек с запятой, но это в любом случае нежелательный побочный эффект
+
+Парсер радикально подменил поведение изначального кода, а в определённых случаях он сделал **абсолютно неправильные выводы**.
+
+### "Висящие" скобки
+
+Если парсер встречает "висящую" скобку, то он **не** вставляет точку с запятой.
+
+    log('тестируем!')
+    (options.list || []).forEach(function(i) {})
+
+Такой код трасформируется в строку
+
+    log('тестируем!')(options.list || []).forEach(function(i) {})
+
+**Чрезвычайно** высоки шансы, что `log` возращает **не** функцию; таким образом, эта строка вызовет `TypeError` с сообщением о том, что `undefined не является функцией`.
+
+### Заключение
+
+Настоятельно рекомендуем **никогда** не забывать ставить точку с запятой; так же рекомендуется оставлять скобки на одной строке с соответствующим оператором и никогда не опускать их для выражений с использованием `if` / `else`. Оба этих совета не только повысят читабельность вашего кода, но и предотвратят от изменения поведения кода, произведённого парсером втихую.
+