Merge branch 'master' of https://github.com/BonsaiDen/JavaScript-Garden

Conflicts:
	template/template.html

Author: ZhangYiJiang

.gitignore

@@ -1,3 +1,2 @@
-/index.html
-/garden.css
-*.tmp
+/html/index.html
+

README.md

@@ -1,30 +1,44 @@
-JavaScript Garden - A Guide for JavaScript Core
-===============================================
+JavaScript Garden
+=================
 
 **JavaScript Garden** is a growing collection of documentation about the most 
-quirky parts of the JavaScript. It gives advice to avoid common coding
-mistakes, subtle bugs, as well as performance issues non expert JavaScript
-programmers may encounter on their endeavours into the depths of the language.
+quirky parts of the JavaScript programming language. It gives advice to 
+avoid common mistakes, subtle bugs, as well as performance issues and bad 
+practices that non-expert JavaScript programmers may encounter on their 
+endeavours into the depths of the language.
 
 JavaScript Garden does **not** insist on teaching JavaScript. Former knowledge
-of the language is recommended in order to understand the topics covered in this
-guide.
+of the language is strongly recommended in order to understand the topics covered
+in this guide. In order to learn the basics of the language, please head over to 
+the excellent [guide][1] on the Mozilla Developer Network.
 
-TODO
-----
+### The authors
 
-Besides a lot of copy-editing and rewording / styling for consistency, the
-following topics are currently missing from the guide:
+This guide is the work of two lovely Stack Overflow users, [Ivo Wetzel][6]
+(Writing) and [Zhang Yi Jiang][5] (Design).
 
- - The evil `eval`
- - The Global Object
- - Casting of Values
- - Converting of Numbers
+If case you are interested in additional guidance or reviews concerning your JavaScript 
+projects, Ivo Wetzel offers these on a freelance basis. Please feel free to 
+contact him via [e-mail][7] for further details.
 
-License
--------
+### Contributors
 
-JavaScript Garden is published under the MIT license and hosted on
-[GitHub](https://github.com/BonsaiDen/JavaScript-Garden). If you find errors or
-typos please file an issue or a pull request on the repository.
+ - [Caio Romão][8] (Spelling corrections)
+ - [Andreas Blixt][9] (Language corrections)
+
+### License
+
+JavaScript Garden is published under the [MIT license][2] and hosted on
+[GitHub][4]. If you find errors or typos please [file an issue][3] or a pull 
+request on the repository.
+
+[1]: https://developer.mozilla.org/en/JavaScript/Guide
+[2]: https://github.com/BonsaiDen/JavaScript-Garden/blob/next/LICENSE
+[3]: https://github.com/BonsaiDen/JavaScript-Garden/issues
+[4]: https://github.com/BonsaiDen/JavaScript-Garden
+[5]: http://stackoverflow.com/users/313758/yi-jiang
+[6]: http://stackoverflow.com/users/170224/ivo-wetzel
+[7]: mailto:[email protected]
+[8]: https://github.com/caio
+[9]: https://github.com/blixt
 

doc/arguments.md

@@ -1,23 +1,86 @@
-### Function Arguments
+## The `arguments` object
 
-Inside a JavaScript function you have access to a special variable called
-`arguments`, which is a list of the parameters the function was called with. This 
-is useful when writing functions that deal with variable number of arguments. 
+Every function scope in JavaScript can access the special variable `arguments`.
+This variable holds a list of all the arguments that were passed to the function.
 
-It's important to know that `arguments` is **not** an `Array`, it has some of
-the semantics of an array - namely the `length` property - but it does not
-inherit from `Array.prototype`, it is an `Object`.
+> **Note:** In case `arguments` has already been defined inside the functions
+> scope either via a `var` statement or being the name of a formal parameter,
+> the `arguments` object will not be created.
+
+The `arguments` variable is **not** an `Array`. While it has some of the 
+semantics of an array - namely the `length` property - it does not inherit from 
+`Array.prototype` and is in fact an `Object`.
+
+Due to this, it is not possible to use standard array methods like `push`,
+`pop` or `slice` on `arguments`. While iteration with a plain `for` loop works 
+just fine, it is necessary to convert it to a real `Array` in order to use the 
+array like methods on it.
+
+### Converting to an array
+
+The code below will return a new `Array` containing all the elements of the 
+`arguments` object.
 
-Due to this fact, one cannot use the standard array methods like `push`, `pop`,
-`slice` etc. with it. While iteration with a plain `for` loop works just fine,
-one has convert it to a real `Array` in order to use the named methods.
-    
     Array.prototype.slice.call(arguments);
 
-This will return a new `Array` containing all the elements from the `arguments`
-object, note that this is **slow**, try to avoid at all costs in performance
-critical code. 
+This conversion is **slow**, it is not recommended to use it in performance 
+critical sections of code.
+
+### Modification "magic"
+
+The `arguments` object creates getter and setter functions for both its properties
+as well as the functions formal parameters.
+
+As a result, changing the value of a formal parameter will also change the value
+corresponding formal parameter, and the other way around.
+
+    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);
+
+> **ES5 Note:** These getters and setters are not created in strict mode.
+
+### Performance myths and truths
+
+The `arguments` is, except for the two cases named at the start of this section,
+always created. It doesn't matter whether it is used or not. Both getters and
+setters are **always** created; thus, using it has nearly no performance impact
+at all, especially not in real world code where there is more than an access to
+the arguments object properties.
+
+However, there is one case which will drastically reduce the performance in
+modern JavaScript engines. That case is the use of `arguments.callee`.
+
+    function foo() {
+        arguments.callee; // do something with this function object
+        arguments.callee.caller; // and the calling function object
+    }
+
+    function bigLoop() {
+        for(var i = 0; i < 100000; i++) {
+            foo(); // Would normally be inlined...
+        }
+    }
+
+In the above code, `foo` can no longer be a subject to [inlining][1] since it 
+needs to know about both itself and its caller. This not only defeats possible 
+performance gains due to inlining, it also breaks encapsulation since the 
+function may now be dependent on being called in a specific context.
+
+It is highly recommended to **never** make use of `arguments.callee` or any of 
+its properties.
+
+> **ES5 Note:** In strict mode, `arguments.callee` will throw a `TypeError` since 
+> its use has been deprecated.
 
-> **Note:** Don't use `arguments` as a parameter name for functions, since it will 
-> [override](#scopes) the default `arguments` object.
+[1]: http://en.wikipedia.org/wiki/Inlining
 

doc/arrayctor.md

@@ -0,0 +1,27 @@
+## The `Array` constructor
+
+Since the `Array` constructor is ambiguous in how it deals with its parameters,
+it is recommended to always use the `[]` notation when creating new arrays.
+
+    [1, 2, 3]; // Result: [1, 2, 3]
+    new Array(1, 2, 3); // Result: [1, 2, 3]
+
+    [3]; // Result: [3]
+    new Array(3); // Result: [undefined, undefined, undefined] 
+    new Array('3') // Result: ['3']
+
+In cases when there is only one argument being passed to the `Array` constructor,
+and that argument is a `Number`, the constructor will use that number as the 
+*length* of the new array to be created.
+
+This behavior only comes in handy in a few cases, like repeating a string, in
+which it avoids the use of a `for` loop.
+
+    new Array(count + 1).join(stringToRepeat);
+
+### In conclusion
+
+The use of the `Array` constructor should be avoided as much as possible. The `[]` 
+notation is definitely preferred. It is shorter and has a clearer syntax; thus, 
+it also  increases the readability of code.
+

doc/arrays.ctor.md

@@ -1,63 +1,60 @@
-### Arrays
+## Arrays
 
-Although the `Array` in JavaScript is an `Object`, there's no good reason to use
-the [for in loop](#forinloop) in order to iterate over it. In fact there
-a number of very good reasons **against** the use of `for in` on an `Array`.
+Although arrays in JavaScript are objects, there are no good reasons to use
+the [for in loop](#forinloop) in for iteration on them. In fact there are a 
+number of good reasons **against** the use of `for in` on arrays.
 
-> **Note:** There are **no** so called *associative arrays* in JavaScript. 
-> JavaScript only has [objects](#objects) for mapping keys to values. And while 
-> *associative arrays* **preverse** order, objects do **not**.
+> **Note:** JavaScript arrays are **not** *associative arrays*. JavaScript only 
+> has [objects](#objects) for mapping keys to values. And while associative 
+> arrays **preserve** order, objects do **not**.
 
-While it may seem like a good choice at first, to trade the some speed against
-the readability of the `for in` construct, this has **major** implications on
-performance.
+Since the `for in` loop enumerates all properties on the prototype chain and 
+the only way to exclude those properties is to use 
+[`hasOwnProperty`](#hasownproperty), it is already up to **twenty times** slower
+than a normal `for` loop.
 
-The `for in` does in fact iterate over the indexes of an `Array`. But it does
-also traverse the prototype chain. So one already has to use `hasOwnProperty` in
-order to make sure to filter out unwanted properties, and still if any
-additional properties happen to be defined on the array, they will still make it
-through this filter.
+### Iteration
 
-Combining the already slow nature of the prototype traversing `for in` with the
-use of `hasOwnProperty` results in a performance degradation of a factor of up
-to **20x**.
-
-So if you want to iterate over an `Array` in JavaScript, **always** use the
-classic `for` loop construct.
+In order to achieve the best performance when iterating over arrays, it is best
+to use the classic `for` loop.
 
     var list = [1, 2, 3, 4, 5, ...... 100000000];
     for(var i = 0, l = list.length; i < l; i++) {
         console.log(list[i]);
     }
 
-As you can see, there's one extra catch in the above example. That is the
-caching of the length via `l = list.length`.
+There is one extra catch in the above example, which is the caching of the 
+length of the array via `l = list.length`.
+
+Although the `length` property is defined on the array itself, there is still an
+overhead for doing the lookup on each iteration of the loop. And while recent 
+JavaScript engines **may** apply optimization in this case, there is no way of
+telling whether the code will run on one of these newer engines or not. 
 
-Although the `length` property is defined on the array itself, there's still an
-overhead for doing the lookup on each iteration. And while recent JavaScript
-engines **may** apply optimization in this case, one can never be sure that
-those optimizations are actually in place, nor can one be sure whether they
-reach the speed of the above caching. In fact leaving out the caching may result
-in a performance degradation of a factor of up to **2x** (and even more in older
-engines).
+In fact, leaving out the caching may result in the loop being only **half as
+fast** as with the cached length.
 
-**The length Property**
+### The `length` property
 
-The `length` property of an `Array` is not just a plain property. While its 
-`getter` just returns the number of elements in the array, its `setter` on 
-the other hand can be used to **truncate** the array.
+While the *getter* of the `length` property simply returns the number of
+elements that are contained in the array, the *setter* can be used to 
+**truncate** the array.
 
     var foo = [1, 2, 3, 4, 5, 6];
     foo.length = 3;
     foo; // [1, 2, 3]
+
     foo.length = 6;
     foo; // [1, 2, 3]
 
-As one can see, assigning a smaller length truncates the array, but increasing 
-the length it has no effect at all.
+Assigning a smaller length does truncate the array, but increasing the length 
+does not have any effect on the array.
+
+### In conclusion
+
+For the best performance it is recommended to always use the plain `for` loop
+and cache the `length` property. The use of `for in` on an array is a sign of
+badly written code that is prone to bugs and bad performance. Additionally, 
+never should any assumptions be made whether the JavaScript engine will apply 
+optimization to the code or not.
 
-#### Best Practices
-Always use the `for` construct and cache the length to achieve the best 
-performance, don't make any assumptions about the JavaScript engine optimizing 
-**anything**.
-