Further cleanup, rewriting etc.

Author: BonsaiDen

doc/arguments.md

@@ -1,16 +1,17 @@
 ## Function arguments
 
-Inside of functions JavaScript injects a special variable into the scope of the
-function. This variable is called `arguments`, and holds a list of all the
-arguments that were passed to the function.
+Inside the scope of a function JavaScript injects a special variable into. This 
+variable is called `arguments` and 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`, and is in fact an `Object`.
+This `arguments` variable 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 in fact an `Object`.
 
 Due to this, it is not possible to use standard array methods like `push`,
-`pop` or `slice` on it. While iteration with a plain `for` loop works just fine,
-one has convert it to a real `Array` in order to use the those methods.
+`pop` or `slice` on `arguments`. While iteration with a plain `for` loop works 
+just fine, one has convert it to a real `Array` in order to use the array like 
+methods.
 
 ### Converting to an array
 

doc/constructors.md

@@ -1,13 +1,11 @@
 ## Constructors 
 
-Constructors in JavaScript are another thing many people get wrong, but actually, their
-workings are pretty simple to understand.
-
-Any function call that is preceded by the `new` keyword acts as a constructor.
+Constructors in JavaScript are yet again different from many other languages. Any
+function call that is preceded by the `new` keyword acts as a constructor.
 
 Inside the constructor (the called function) the value of `this` refers to a 
-newly created `Object`. The `prototype` of this **new** object is set to the 
-`prototype` of the function object that was called.
+newly created `Object`. The [`prototype`](#prototype) of this **new** object is 
+set to the `prototype` of the function object that was called.
 
 If the function that was called has no explicit `return` statement, then it
 implicitly returns the value of `this` (the new object). Otherwise it returns
@@ -26,17 +24,15 @@ the value of the `return` statement.
 The above calls `Foo` as constructor and sets the `prototype` of the newly
 created object to `Foo.prototype`.
 
-Keep in mind that if you don't use the `new` keyword the function will **not**
+Keep in mind that if you don not use the `new` keyword the function will **not**
 return a new object. While it might still work due to how
 [`this`](#how-this-works-in-javascript) works in JavaScript, it will use the
-*global* object as the value of `this` and therefore result in completely
-unexpected results.
+*global* object as the value of `this`.
 
 ### Factories
 
-If you want to omit the `new` keyword you can do that by - as stated above - 
-explicitly returning from the constructor, which essentially leaves you with a
-factory.
+In order to be able to omit the `new` keyword, the constructor function has to 
+explicitly return a value.
 
     function Bar() {
         var value = 1;
@@ -46,20 +42,60 @@ factory.
             }
         }
     }
+    Bar.prototype = {
+        foo: function() {}
+    };
 
     new Bar();
     Bar();
 
-Now, both these calls return the exact same thing, a newly create object which
+Both these calls return the exact same thing, a newly create object which
 has a property called `method` which is a [Closure](#closures-and-references).
 
-Since `Bar` doesn't make any use of `this`, the `new` keyword is superfluous
-here. But from a technical point of view, this is no longer a *constructor*.
+Also note that the call `new Bar()` does **not** affect the prototype of the
+returned object. While the prototype will be set on the newly created object,
+`Bar` never returns that object.
+
+So in the above example there is no functional difference between using and
+omitting the `new` keyword.
+
+
+### Creating new objects via factories
+
+An often made recommendation is to **not** use `new` since forgetting the use of 
+it may lead to a lot of bugs.
+
+In order to create new object one now has to use a factory and set up the new
+object inside it.
+
+    function Foo() {
+        var obj = {};
+        obj.value = 'blub';
+
+        var private = 2;
+        obj.someMethod = function(value) {
+            this.value = value;
+        }
+
+        obj.getPrivate = function() {
+            return private;
+        }
+        return obj;
+    }
+
+While the above is robust against forgetting to use `new` and makes the use of
+[private variables](#closures) certainly easier, it comes with some down sides.
+
+ 1. It uses more memory since the created objects do **not** share the methods
+ 2. In order to inherit the factory needs to copy all the methods from another
+    object
+ 3. It somehow goes against the spirit of the language, by dropping prototype
+    chain just because a left out `new` keyword can break code
 
-### Best Practices
+### Best practices
 
-Make sure you know whether you're calling a *constructor* or a *factory*. 
-If in doubt, always use the `new` keyword, since it doesn't have any side effect
-when its not required, while leaving it out can lead to subtle and
-hard to track down bugs.
+While omitting the `new` keyword might lead to bugs, it is certainly not a reason
+to drop the use of prototypes altogether. In the end it comes down which
+solution is better suited for the needs of the application, it is especially
+important to choose a specific style of object creation and stick with it.
 

doc/scopes.md

@@ -6,16 +6,15 @@ scope*.
 
 > **Note:** When not used in an assignment or as a function argument, the `{...}`
 > notation will get interpreted as a block statement and **not** as an `Object`. 
-> This, in conjunction with 
-> [automatic insertion of semicolons](#semicolon), can lead
-> to subtle errors.
+> This, in conjunction with [automatic insertion of semicolons](#semicolon), 
+> can lead to subtle errors.
 
-Additionally, there are no distinct namespaces in JavaScript, this means that 
+Additionally, there are no distinct namespaces in JavaScript. This means that 
 everything gets defined in **one** globally shared namespace.
 
-Each time one references a variable, JavaScript will traverse through the scopes 
-upwards until it finds it. In the case that it reaches the global scope and still 
-can't find the requested name it will raise a `ReferenceError`.
+Each time a variable is referenced, JavaScript will traverse upwards through all 
+the scopes until it finds it. In the case that it reaches the global scope and 
+still has not found the requested name, it will raise a `ReferenceError`.
 
 ### The Bane of global Variables
 
@@ -29,8 +28,8 @@ The above two scripts do **not** have the same effect. Script A defines a
 variable called `foo` in the *global* scope and script B defines a `foo` in the
 *local* scope.
 
-Again, that's **not** at all the same effect, forgetting to use a `var` can have
-major implications.
+Again, that is **not** at all the same effect, not using `var` can have major 
+implications.
 
     // global scope
     var foo = 42;
@@ -42,10 +41,9 @@ major implications.
     foo; // 21
 
 Leaving out the `var` statement will override the value of `foo`, this might not
-seem like a big deal at first, but consider you have a ten-thousand line
+seem like a big deal at first, but consider having a ten-thousand line
 JavaScript file with lots and lots of different variable names, not using `var`
-will introduce bugs for sure. And additionally those bugs are very often hard to
-track down.
+will introduce hard to track down bugs.
 
 For example, when using generic variable names like `i` in loops.
 
@@ -63,43 +61,42 @@ For example, when using generic variable names like `i` in loops.
     }
 
 The outer loop will terminate after the first call to `subLoop` since that
-function had overriden the global value of `i`. Using a `var` for the second
-`for` loop would have easily avoided this, therefore never leave out `var`
-unless you really want to access the variable of an outer scope.
+function overwrites the global value of `i`. Using a `var` for the second
+`for` loop would have easily avoided this error, therefore `var` should never be
+left out unless the desired effect **is** to affect the outer scope.
 
-### Local Variables
+### Local variables
 
-If one wants to declare a variable *local* to the current scope thes have to use 
-the `var` keyword. **Always** use the `var` keyword when declaring variables
-otherwise you might **overriding** things that were already defined in outer
-scopes.
+The only source for local variables in JavaScript are [function](#functions)
+parameters and variables that were declared with the `var` statement.
 
     // global scope
     var foo = 1;
     var bar = 2;
+    var i = 2;
 
-    function test() {
-
+    function test(i) {
         // local scope of the function test
+        i = 5;
+
         var foo = 3;
         bar = 4;
     }
+    test(10);
 
-In the above, `var foo` inside of `test` will create a new variable that is in
-the *local* scope. Therefore the value of the *global* `foo` does **not** get
-changed. But the assignment `bar = 4` will override the value of the *global*
-`bar` due to the missing `var` keyword.
+While `foo` and `i` are local variables inside the scope of the function `test`,
+the assignment of `bar` will override the global variable.
 
-### Name Resolution Order
+### Name resolution order
 
-All scopes in JavaScript - including the global one, have the name 
-[this](#this) defined in them, which refers to the 
-"current object". Function scopes also have the name
-[arguments](#arguments) defined, which contains the arguments that were 
-passed to a function.
+All scopes in JavaScript - including the global one - have the name 
+[this](#this) defined in them, which refers to the  "current object". 
 
-For example, when you try to access a variable named `foo` inside a function 
-scope, JavaScript will lookup the name in the following order:
+Function scopes also have the name [arguments](#arguments) defined, which 
+contains the arguments that were passed to a function.
+
+For example, when trying to access a variable named `foo` inside the scope of a 
+function, JavaScript will lookup the name in the following order:
 
  1. In case there's a `var foo` statement in the current scope use that.
  2. If one of the function parameters is named `foo` use that.
@@ -111,9 +108,9 @@ scope, JavaScript will lookup the name in the following order:
 
 ### Namespaces
 
-One common problem of having only one global namespace is, that its very easy to 
-run into problems where variable names clash. Luckily this can be easily avoided 
-with the help of *anoynmous function wrappers*.
+A common problem of having only one global namespace is that it is very easy to 
+run into problems where variable names clash. But this can be easily avoided 
+with the help of anonymous *function wrappers*.
 
     (function() {
         // a self contained "namespace"
@@ -124,16 +121,29 @@ with the help of *anoynmous function wrappers*.
 
     })(); // execute the function immediately
 
-By default you cannot just call a function, you need to **evaluate** it first. 
-In this example, this is done by wrapping the 
-[function expression](#functions) in parenthesis. While this is 
-the most common style to do this, everything else that forces the function to be 
-evaluated works just as well, like for example `+function(){}()`.
+
+Since a unnamed functions are not considered as [statement](#functions), they
+get interpreted as expression, in order to run those functions they must fist be
+evaluate and then called.
+
+    ( // evaluate the function inside the paranthesis
+    function() {}
+    ) // and return the function object
+    () // call the result of the evaluation
+
+There are other ways for evaluating and calling the function expression which - 
+while different in syntax - do the exact same thing.
+
+    // Two other ways
+    +function(){}();
+    (function(){}());
 
 ### Best Practices
 
-Always use the *anonymous wrapper* to encapsulate your code in case there's any 
-chance it might get used by someone else in their project. Also never define any 
-variables in the *global* namespace, always use `var` to limit the scope of your 
-variables.
+It is recommended to always use an *anonymous wrapper* for encapsulating code in 
+its own namespace. This does not only protect against name clashes, but it also
+allows for better modularization.
+
+Additionally the use of global variables is consider **bad practice**, any use
+of them indicates badly written, hard to maintain code.
 

doc/this.md

@@ -1,7 +1,8 @@
 ## How `this` works
 
-JavaScript has, at first glance, a very strange concept of what `this` refers to.
-There are exactly five different ways in which the value of `this` can get set.
+JavaScript has a different concept of what `this` refers to than most other
+languages do. There are exactly **five** different ways in which the value of `this` 
+can be bound in the language.
 
 ### The global scope
 
@@ -25,32 +26,33 @@ In this example `this` will refer to `test`.
 
     new foo(); 
 
-A function call that's preceded by the `new` keyword acts as
+A function call that is preceded by the `new` keyword acts as
 a [constructor](#constructors). Inside the function `this` will refer to a newly
 created `Object`.
 
 ### Explicit setting
 
-    function foo(a, b, c) {
-    }
+    function foo(a, b, c) {}
                           
     var bar = {};
     foo.call(bar, [1, 2, 3]);
     foo.apply(bar, 1, 2, 3);
 
-When using the `call` or `apply` methods of `Function.prototype`, one can 
-explicitly set the value of `this` inside the called function, so in the above
-case the *method case* does **not** apply, and `this` inside of `foo` will be
-set to `bar`.
+When using the `call` or `apply` methods of `Function.prototype`, the value of
+`this` inside the called function gets explicitly set to the first arguments of
+those function calls. 
+
+In the above example the *method case* does **not** apply, and `this` inside of 
+`foo` will be set to `bar`.
 
 > **Note:** `this` **cannot** be used to refer to the object inside of an `Object`
 > literal. So `var obj = {me: this}` will **not** result in `me` referring to
 > `obj`, since `this` gets determined by one of the above cases.
 
-### Common Pitfalls
+### Common pitfalls
 
 While most of these cases make sense, the first one is considered a mis-design 
-by many people since it's **never** of any practical use, but leads to many bugs.
+by many people as it is **never** of any practical use.
 
     Foo.method = function() {
         function test() {
@@ -73,20 +75,20 @@ variable inside of `method` which refers to `Foo`.
         test();
     }
 
-`that` is just a normal name, but it's a common idiom to use it as a reference
-to an outer `this`. In combination with [Closures](#closures), 
-this can also be used to pass `this` around.
+`that` is just a normal name, but it is commonly used for the reference to an 
+outer `this`. In combination with [Closures](#closures), it can also be used to 
+pass `this` values around.
 
-### Assigning Methods
+### Assigning methods
 
-Another thing that does **not** work in JavaScript is **assigning** a method to
-a variable.
+Another thing that does **not** work in JavaScript is **assigning** a method
+reference to a variable.
 
     var test = someObject.methodTest();
     test();
 
-Again due to the first case, `test` now acts like like a plain function call
-therefore the `this` inside it will not refer to `someObject` any more.
+Again due to the first case, `test` now acts like like a plain function call and 
+therefore the `this` inside it will no longer refer to `someObject`.
 
 While the late binding of `this` might seem like a bad thing, it is fact what
 makes [prototypical inheritance](#prototype) work. 
@@ -102,8 +104,9 @@ makes [prototypical inheritance](#prototype) work.
 When `method` gets called on a instance of `Bar`, `this` will now refer to that
 instance. 
 
-### Best Practices
+### Best practices
+
+Understand the exact workings of `this` and not trying to work around them is a 
+requirement for writing efficient, well designed code that can make use of 
+features such as [prototypical inheritance](#prototype) and [closures](#closures). 
 
-Don't try to work around the behavior of `this` in JavaScript. Instead,
-**understand** how and why it works the way it does. Otherwise you'll end up with
-a lot of bugs that seem to be there for no good reason.