Merge branch 'master' of https://github.com/bebraw/JavaScript-Garden into fn-translation

Author: ZhangYiJiang

doc/fi/array/constructor.md

@@ -0,0 +1,25 @@
+## `Array`-konstruktori
+
+`Array`-oletuskonstruktorin käytös ei ole lainkaan yksiselitteistä. Tämän vuoksi suositellaankin, että konstruktorin sijasta käytetään literaalinotaatiota `[]`.
+
+    [1, 2, 3]; // Tulos: [1, 2, 3]
+    new Array(1, 2, 3); // Tulos: [1, 2, 3]
+
+    [3]; // Tulos: [3]
+    new Array(3); // Tulos: []
+    new Array('3') // Tulos: ['3']
+
+Mikäli `Array`-konstruktorille annetaan vain yksi argumentti ja se on tyypiltään `Number`, konstruktori palauttaa uuden *harvan* taulukon, jonka `length`-attribuutti on asetettu annetun numeron mukaisesti. On tärkeää huomata, että **ainoastaan** `length` asetetaan tällä tavoin, todellisia taulukon indeksejä ei alusteta.
+
+    var arr = new Array(3);
+    arr[1]; // undefined
+    1 in arr; // false, indeksiä ei ole alustettu
+
+Tämä on käytännöllistä vain harvoin, kuten merkkijonon toiston tapauksessa. Tällöin voidaan välttää `for-luupin` käyttämistä.
+
+    new Array(count + 1).join(stringToRepeat);
+
+### Yhteenveto
+
+`Array`-konstruktorin käyttöä tulee käyttää niin paljon kuin suinkin mahdollista. Sen sijaan on suositeltavaa käyttää literaalinotaatiota. Literaalit ovat lyhyempiä ja niiden syntaksi on selkeämpi. Tämän lisäksi ne tekevät koodista luettavampaa.
+

doc/fi/array/general.md

@@ -0,0 +1,40 @@
+## Taulukon iterointi ja attribuutit
+
+Vaikka taulukot ovatkin JavaScript-olioita, niiden tapauksessa ei välttämättä kannata käyttää [`for in loop`](#object.forinloop)-luuppia. Pikemminkin tätä tapaa tulee **välttää**.
+
+> **Huomio:** JavaScript-taulukot **eivät ole** *assosiatiivisia*. JavaScriptissa ainoastaan [oliot](#object.general) ovat avain-arvo-mappauksia. On huomattavaa, että toisin kuin assosiatiiviset taulukot, oliot **eivät** säilytä järjestystään.
+
+`for in`-luuppi iteroi kaikki prototyyppiketjun sisältämät ominaisuudet. Tämän vuoksi tulee käyttää erityistä  [`hasOwnProperty`](#object.hasownproperty)-metodia, jonka avulla voidaan taata, että käsitellään oikeita ominaisuuksia. Tästä johtuen iteroint on jo lähtökohtaisesti jopa **kaksikymmentä** kertaa hitaampaa kuin normaalin `for`-luupin tapauksessa.
+
+### Iterointi
+
+Taulukkojen tapauksessa paras suorituskyky voidaan saavuttaa käyttämällä klassista `for`-luuppia.
+
+    var list = [1, 2, 3, 4, 5, ...... 100000000];
+    for(var i = 0, l = list.length; i < l; i++) {
+        console.log(list[i]);
+    }
+
+Edelliseen esimerkkiin liittyy yksi mutta. Listan pituus on tallennettu välimuistiin erikseen käyttämällä `l = list.length`-lauseketta.
+
+Vaikka `length`-ominaisuus määritelläänkin taulukossa itsessään, arvon hakeminen sisältää ylimääräisen operaation. Uudehkot JavaScript-ympäristöt **saattavat** optimoida tämän tapauksen. Tästä ei kuitenkaan ole mitään takeita.
+
+Todellisuudessa välimuistin käytön pois jättäminen voi hidastaa luuppia jopa puolella.
+
+### `length`-ominaisuus
+
+`length`-ominaisuuden *getteri* palauttaa yksinkertaisesti taulukon sisältämien alkioiden määrän. Sen *setteriä* voidaan käyttää taulukon **typistämiseen**.
+
+    var foo = [1, 2, 3, 4, 5, 6];
+    foo.length = 3;
+    foo; // [1, 2, 3]
+
+    foo.length = 6;
+    foo; // [1, 2, 3]
+
+Pituuden pienemmäksi asettaminen typistää taulukkoa. Sen kasvattaminen ei kuitenkaan vaikuta mitenkään.
+
+### Yhteenveto
+
+Parhaan suorituskyvyn kannalta on parhainta käyttää tavallista `for`-luuppia ja tallentaa `length`-ominaisuus välimuistiin. `for in`-luupin käyttö taulukon tapauksessa on merkki huonosti kirjoitetusta koodista, joka on altis bugeille ja heikolle suorituskyvylle.
+

doc/fi/core/eval.md

@@ -0,0 +1,39 @@
+## Miksi `eval`-funktiota tulee välttää
+
+`eval` suorittaa JavaScript-koodia sisältävän merkkijonon paikallisessa näkyvyysalueessa.
+
+    var foo = 1;
+    function test() {
+        var foo = 2;
+        eval('foo = 3');
+        return foo;
+    }
+    test(); // 3
+    foo; // 1
+
+`eval` suoritetaan paikallisessa näkyvyysalueessa ainoastaan kun sitä kutsutaan **suorasti** *ja* kutsutun funktion nimi on todellisuudessa `eval`.
+
+    var foo = 1;
+    function test() {
+        var foo = 2;
+        var bar = eval;
+        bar('foo = 3');
+        return foo;
+    }
+    test(); // 2
+    foo; // 3
+
+`eval`-funktion käyttöä tulee välttää **ehdottomasti**. 99.9% sen "käyttötapauksista" voidaan toteuttaa **ilman** sitä.
+    
+### Piilotettu `eval`
+
+[Aikakatkaisufunktiot](#other.timeouts) `setTimeout` and `setInterval` voivat kumpikin ottaa merkkijonon ensimmäisenä argumenttinaan. Kyseinen merkkijono suoritetaan **aina** globaalissa näkyvyysalueessa, koska tuolloin `eval`-funktiota kutsutaan epäsuorasti.
+
+### Turvallisuusongelmat
+
+`eval` on myös turvallisuusongelma. Se suorittaa **minkä tahansa** sille annetun koodin. Tämän vuoksi sitä ei tule **ikinä** käyttää tuntemattomasta tai epäluotttavasta lähteestä tulevien merkkijonojen kanssa.
+
+### Yhteenveto
+
+`eval`-funktiota ei pitäisi käyttää koskaan. Mikä tahansa sitä käyttävä koodi on kyseenalaista sekä suorituskyvyn että turvallisuuden suhteen. Mikäli jokin tarvitsee `eval`-funktiota toimiakseen, tulee sen suunnittelutapa kyseenalaistaa. Tässä tapauksessa on parempi suunnitella toisin ja välttää `eval`-funktion käyttöä.
+

doc/fi/core/semicolon.md

@@ -0,0 +1,100 @@
+## Automaattiset puolipisteet
+
+Vaikka JavaScript käyttääkin C:n tapaista syntaksia, se **ei** pakota käyttämään puolipisteitä. Niiden käyttöä voidaan halutessa välttää.
+
+Tästä huolimatta JavaScript ei kuitenkaan ole puolipisteetön kieli. Se tarvitsee niitä ymmärtääkseen lähdekoodia. Tämän vuoksi JavaScript-parseri lisää niitä tarpeen mukaan **automaattisesti**.
+
+    var foo = function() {
+    } // parsimisvirhe, lisätään puolipiste
+    test()
+
+Lisäys tapahtuu ja parseri yrittää uudelleen.
+
+    var foo = function() {
+    }; // ei virhettä, parsiminen jatkuu
+    test()
+
+Automaattista puolipisteiden lisäämistä pidetään eräänä JavaScriptin **suurimmista** suunnitteluvirheistä. Tämä johtuu siitä, että se voi muuttaa tapaa, jolla koodi käyttäytyy.
+
+### Kuinka se toimii
+
+Alla oleva koodi ei sisällä puolipisteitä. Täten niiden lisääminen jää parserin tehtäväksi.
+
+    (function(window, undefined) {
+        function test(options) {
+            log('testing!')
+
+            (options.list || []).forEach(function(i) {
+
+            })
+
+            options.value.test(
+                'long string to pass here',
+                'and another long string to pass'
+            )
+
+            return
+            {
+                foo: function() {}
+            }
+        }
+        window.test = test
+
+    })(window)
+
+    (function(window) {
+        window.someLibrary = {}
+
+    })(window)
+
+Alla parserin arvaus.
+
+    (function(window, undefined) {
+        function test(options) {
+
+            // Not inserted, lines got merged
+            log('testing!')(options.list || []).forEach(function(i) {
+
+            }); // <- lisätty
+
+            options.value.test(
+                'long string to pass here',
+                'and another long string to pass'
+            ); // <- lisätty
+
+            return; // <- lisätty, rikkoo return-lauseen
+            { // kohdellaan lohkona
+
+                // nimike ja yhden lausekkeen lause
+                foo: function() {} 
+            }; // <- lisätty
+        }
+        window.test = test; // <- lisätty
+
+    // Rivit yhdistettiin jälleen
+    })(window)(function(window) {
+        window.someLibrary = {}; // <- lisätty
+
+    })(window); //<- lisätty
+
+> **Huomio:** JavaScript-parseri ei käsittele return-lauseita ja rivivaihtoja "kunnolla". Vaikka tämä ei välttämättä olekaan parserin vika, voi siitä seurata epämiellyttäviä sivuvaikutuksia.
+
+Yllä olevassa tapauksessa parseri muutti huomattavasti koodin käytöstä. Joissain tapauksissa se tekee kokonaan **väärän asian**.
+
+### Johtavat sulkeet
+
+Parseri **ei** lisää puolipistettä johtavien sulkeiden tapauksessa.
+
+    log('testing!')
+    (options.list || []).forEach(function(i) {})
+
+Koodi muuttuu seuraavaksi.
+
+    log('testing!')(options.list || []).forEach(function(i) {})
+
+On **hyvin** mahdollista, että `log` **ei** palauta funktiota. Tästä johtuen yllä oleva palauttanee `TypeError`-virheen, joka toteaa että `undefined ei ole funktio`.
+
+### Yhteenveto
+
+On suositeltavaa ettei puolipisteitä jätetä pois **milloinkaan**. Tämän lisäksi sulut kannattaa pitää niitä vastaavien lausekkeiden kanssa samalla rivillään. `if` ja `else`-lauseiden tapauksessa sulkuja kannattaa käyttää aina. Sen lisäksi että edellä mainitut suositukset tekevät koodista johdonmukaisempaa, estävät ne myös JavaScript-parseria muuttamasta sen käytöstapaa.
+

doc/fi/core/undefined.md

@@ -0,0 +1,54 @@
+## `undefined` ja `null`
+
+JavaScript sisältää kaksi erillistä arvoa `ei millekään`. Näistä hyödyllisempti on `undefined`.
+
+### `undefined` ja sen arvo
+
+`undefined` on tyyppi, jolla on vain yksi arvo: `undefined`.
+
+Kieli määrittelee myös globaalin muuttujan, jonka arvo on `undefined`. Myös tätä arvoa kutsutaan nimellä `undefined`. Tämä muuttuja **ei** kuitenkaan ole vakio eikä kielen avainsana. Tämä tarkoittaa siis sitä, että sen *arvo* voidaan ylikirjoittaa.
+
+> **ES5 Huomio:** ECMAScript 5:ssä `undefined`-tyyppiä ei voida *kirjoittaa* **enää** tiukassa moodissa. Sen nimi voidaan kuitenkin jättää katveeseen määrittelemällä esimerkiksi funktio, jonka nimi on `undefined`.
+
+Seuraavat tapaukset palauttavat `undefined`-arvon:
+
+ - Globaalin (muokkaamattoman) muuttujan `undefined` arvon haku.
+ - Puuttuvista `return`-lauseista seuraavat epäsuorat palautusarvot.
+ - `return`-lauseet, jotka eivät palauta selvästi mitään.
+ - Olemattomien ominaisuuksien haut.
+ - Funktioparametrit, joiden arvoa ei ole asetettu.
+ - Mikä tahansa, joka on asetettu arvoon `undefined`.
+
+### Arvon `undefined` muutosten hallinta
+
+Koska globaali muuttuja `undefined` sisältää ainoastaan todellisen `undefined`-tyypin arvon kopion, **ei** sen asettamienn uudelleen muuta *tyypin* `undefined` arvoa.
+
+Kuitenkin, jotta `undefined`-tyypin arvoa voidaan verrata, tulee sen arvo voida hakea jotenkin ensin.
+
+Tätä varten käytetään yleisesti seuraavaa tekniikkaa. Ajatuksena on antaa itse arvo käyttäen [nimetöntä käärettä](#function.scopes).
+
+    var undefined = 123;
+    (function(something, foo, undefined) {
+        // paikallisen näkyvyysalueen undefined 
+        // voi viitata jälleen todelliseen arvoon
+
+    })('Hello World', 42);
+
+Samaan lopputuloksen voidaan päästä myös käyttämällä esittelyä kääreen sisällä.
+
+    var undefined = 123;
+    (function(something, foo) {
+        var undefined;
+        ...
+
+    })('Hello World', 42);
+
+Tässä tapauksessa ainut ero on se, että pakattu versio vie 4 tavua enemmän tilaa 'var'-lauseen vuoksi.
+
+### `null` ja sen käyttötapaukset
+
+Vaikka `undefined`-arvoa käytetäänkin usein perinteisen *null*-arvon sijasta, todellinen `null` (sekä literaali että tyyppi) on enemmän tai vähemmän vain tietotyyppi.
+
+Sitä käytetään joissain JavaScriptin sisäisissä toiminnoissa, kuten prototyyppiketjun pään toteamisessa (`Foo.prototype = null`). Useimmissa tapauksissa se voidaan korvata `undefined`-arvoa käyttäen.
+
+

doc/fi/function/arguments.md

@@ -0,0 +1,94 @@
+## `arguments`-olio
+
+Jokainen JavaScriptin näkyvyysalue pääsee käsiksi erikoismuuttujaan nimeltään `arguments`. Tämä muuttuja sisältää listan kaikista funktiolle annetuista argumenteista.
+
+> **Huomio:** Mikäli `arguments` on jo määritelty funktion sisällä joko näkyvyysalueen, `var`-lauseen tai parametrin kautta, `arguments`-oliota ei luoda.
+
+`arguments`-olio **ei** ole `Array`. Sen semantiikka, erityisesti `length`-ominaisuus, muistuttaa taulukkoa. Tästä huolimatta se ei peri `Array.prototype`:stä ja on itse asiassa `Object`.
+
+Tästä johtuen `arguments`-olioon **ei** voida soveltaa normaaleja taulukkometodeja, kuten `push`, `pop` tai `slice`. Vaikka iterointi onnistuukin `for`-luuppeja käyttäen, tulee se muuttaa aidoksi `Array`-olioksi ennen kuin siihen voidaan soveltaa näitä metodeja.
+
+### Array-olioksi muuttaminen
+
+Alla oleva koodi palauttaa uuden `Array`-olion, joka sisältää `arguments`-olion kaikki jäsenet.
+
+    Array.prototype.slice.call(arguments);
+
+Tämä muutos on luonteeltaan **hidas** eikä sitä suositella käytettävän suorituskykyä vaativissa osissa koodia.
+
+### Argumenttien antaminen
+
+Funktiosta toiselle voidaan antaa argumentteja seuraavasti.
+
+    function foo() {
+        bar.apply(null, arguments);
+    }
+    function bar(a, b, c) {
+        // tee jotain
+    }
+
+Toinen keino on käyttää sekä `call`- että `apply`-funktioita yhdessä ja luoda nopeita, sitomattomia kääreitä.
+
+    function Foo() {}
+
+    Foo.prototype.method = function(a, b, c) {
+        console.log(this, a, b, c);
+    };
+
+    // Luo "metodin" sitomaton versio 
+    // Se ottaa seuraavat parametrit: this, arg1, arg2...argN
+    Foo.method = function() {
+
+        // Tulos: Foo.prototype.method.call(this, arg1, arg2... argN)
+        Function.call.apply(Foo.prototype.method, arguments);
+    };
+
+
+### Muodolliset parametrit ja argumenttien indeksit
+
+`arguments`-olio luo sekä *getter*- että *setter*-funktiot sekä sen ominaisuuksille että myös funktion muodollisille parametreille.
+
+Tästä seuraa, että muodollisen parametrin arvon muuttaminen muuttaa myös `arguments`-olion vastaavan ominaisuuden arvoa ja toisin päin.
+
+    function foo(a, b, c) {
+        arguments[0] = 2;
+        a; // 2                                                           
+
+        b = 4;
+        arguments[1]; // 4
+
+        var d = c;
+        d = 9;
+        c; // 3
+    }
+    foo(1, 2, 3);
+
+### Suorituskykyyn liittyviä myyttejä ja totuuksia
+
+`arguments`-olio luodaan aina paitsi jos se on jo julistettu nimenä funktiossa tai sen muodollisena parametrina. Tämä siitä huolimatta käytetäänkö sitä vai ei.
+
+Sekä *getter*- ja *setter*-funktiot luodaan **aina**. Tästä seuraa, että niiden käytöllä ei ole juurikaan merkitystä suorituskyvyn kannalta.
+
+> **ES5 Huomio:** Näitä *getter*- ja *setter*-funktioita ei luoda tiukassa moodissa.
+
+On kuitenkin eräs tapaus, jossa suorituskyky kärsii. Tämä liittyy `arguments.callee`-ominaisuuden käyttöön.
+
+    function foo() {
+        arguments.callee; // tee jotain tällä funktio-oliolla
+        arguments.callee.caller; // ja kutsuvalla funktio-oliolla
+    }
+
+    function bigLoop() {
+        for(var i = 0; i < 100000; i++) {
+            foo(); // normaalisti tämä olisi inline-optimoitu
+        }
+    }
+
+Yllä olevassa koodissa `foo`-kutsua ei voida [käsitellä avoimesti][1], koska sen tulee tietää sekä itsestään että kutsujasta. Sen lisäksi, että se haittaa suorituskykyä, rikkoo se myös kapseloinnin. Tässä tapauksessa funktio voi olla riippuvainen tietystä kutsuympäristöstä.
+
+On **erittäin suositeltavaa** ettei `arguments.callee`-ominaisuutta tai sen ominaisuuksia käytetä **ikinä**.
+
+> **ES5 Huomio:** Tiukassa moodissa `arguments.callee` palauttaa `TypeError`-virheen, koska se käyttö on vanhennettu.
+
+[1]: http://en.wikipedia.org/wiki/Inlining
+