Skip to content

Commit fe5a4d2

Browse files
committed
A ton more of fixes
1 parent b32e113 commit fe5a4d2

10 files changed

Lines changed: 83 additions & 94 deletions

File tree

‎doc/arguments.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,27 @@
11
## Function arguments
22

3-
Inside the scope of a function JavaScript injects a special variable into. This
4-
variable is called `arguments` and holds a list of all the arguments that were
5-
passed to the function.
3+
JavaScript injects a special variable called `arguments` into the scope of every
4+
function. This variable holds a list of all the arguments that were passed to
5+
the function.
66

77
This `arguments` variable is **not** an `Array`. It has some of the semantics of
88
an array - namely the `length` property - but it does not inherit from
9-
`Array.prototype`. It is in fact an `Object`.
9+
`Array.prototype`, it is in fact an `Object`.
1010

1111
Due to this, it is not possible to use standard array methods like `push`,
1212
`pop` or `slice` on `arguments`. While iteration with a plain `for` loop works
13-
just fine, one has convert it to a real `Array` in order to use the array like
14-
methods.
13+
just fine, it is necessary to convert it to a real `Array` in order to use the
14+
array like methods on it.
1515

1616
### Converting to an array
1717

18+
The code below will return a new `Array` containing all the elements of the
19+
`arguments` object.
20+
1821
Array.prototype.slice.call(arguments);
1922

20-
The above will return a new `Array` containing all the elements of the `arguments`
21-
object. This conversion is **slow**, it is not recommended to use it in
22-
performance critical code.
23+
This conversion is **slow**, it is not recommended to use it in performance
24+
critical sections of code.
2325

2426
> **Note:** Do **not** use `arguments` as the name of a function parameter, due
2527
> to the fact how [name resolution](#scopes) in JavaScript works, the parameter

‎doc/closures.md‎

Lines changed: 16 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11
## Closures and references
22

3-
One of JavaScript's most powerful features is the availability of *closures*.
4-
5-
Closures mean that scopes **always** keep access to the outer scope they were
3+
One of JavaScript's most powerful features is the availability of *closures*,
4+
this means that scopes **always** keep access to the outer scope they were
65
defined in. Since the only scope that JavaScript has is the
7-
[function scope](#scopes), all functions, by default, act like closures.
6+
[function scope](#scopes), all functions, by default, act as closures.
87

98
### Emulating private variables
109

@@ -25,10 +24,10 @@ defined in. Since the only scope that JavaScript has is the
2524
foo.increment();
2625
foo.get(); // 5
2726

28-
In the above example `Counter` returns **two** closures. The function `increment`
29-
as well as the function `get`. Both of these functions keep a **reference** to
30-
the scope of `Counter` and, therefore, always have access to the `count` variable
31-
that was defined in that **very** scope.
27+
Here, `Counter` returns **two** closures. The function `increment` as well as
28+
the function `get`. Both of these functions keep a **reference** to the scope of
29+
`Counter` and, therefore, always have access to the `count` variable that was
30+
defined in that very scope.
3231

3332
### Why private variables work
3433

@@ -41,15 +40,14 @@ interact with it is via the two closures.
4140
count = 1337;
4241
};
4342

44-
This code will **not** change the variable `count` in the scope of `Counter`,
45-
since `foo.hack` was not defined in **that** scope, instead, it will create
46-
(or override) the *global* variable `count`.
43+
The above code will **not** change the variable `count` in the scope of `Counter`,
44+
since `foo.hack` was not defined in **that** scope. It will instead create - or
45+
override - the *global* variable `count`.
4746

4847
### Closures inside loops
4948

50-
One mistake that is often made with closures is that they are used like if they
51-
were copying primitive values, while they are in fact **referencing** the
52-
variables which hold those values.
49+
One often made mistake is to use closures inside of loops, as if they were
50+
copying the value of the loops index variable.
5351

5452
for(var i = 0; i < 10; i++) {
5553
setTimeout(function() {
@@ -61,8 +59,7 @@ The above will **not** output the numbers `0` through `9`, it will simply print
6159
the number `10` ten times.
6260

6361
The *anonymous* function keeps a reference to `i` and at the time `console.log`
64-
gets called, the `for` loop has already finished and updated the value of `i` to
65-
`10`.
62+
gets called, the `for` loop has already finished and the value of `i` is now `10`.
6663

6764
In order to get the desired behavior, it is necessary to create a **copy** of
6865
the value of `i`.
@@ -86,9 +83,9 @@ argument and will receive a copy of the **value** of `i` as its parameter `e`.
8683
The anonymous function that gets passed to `setTimeout` now has a reference to
8784
`e`, which value does **not** get changed by the loop.
8885

89-
There is another possible way of achieving this. It is possible to return a
90-
function from the anonymous wrapper, which will then have the same result as the
91-
code above.
86+
There is another possible way of achieving this; that is to return a function
87+
from the anonymous wrapper, which will then have the same behavior as the code
88+
above.
9289

9390
for(var i = 0; i < 10; i++) {
9491
setTimeout((function(e) {
@@ -98,9 +95,3 @@ code above.
9895
})(i), 1000)
9996
}
10097

101-
### In conclusion
102-
103-
It is important to understand **and** master closures, they are the most powerful
104-
feature of JavaScript and are used pretty much everywhere when it comes to
105-
elegant and efficient code.
106-

‎doc/constructors.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ set to the `prototype` of the function object that was called.
99

1010
If the function that was called has no explicit `return` statement, then it
1111
implicitly returns the value of `this` (the new object). Otherwise it returns
12-
the value of the `return` statement.
12+
the value of the `return` statement, **but** only if `typeof returnValue` is
13+
`object`.
1314

1415
function Foo() {
1516
this.bla = 1;
@@ -24,10 +25,10 @@ the value of the `return` statement.
2425
The above calls `Foo` as constructor and sets the `prototype` of the newly
2526
created object to `Foo.prototype`.
2627

27-
Keep in mind that if you don not use the `new` keyword the function will **not**
28-
return a new object. While it might still work due to how
29-
[`this`](#how-this-works-in-javascript) works in JavaScript, it will use the
30-
*global* object as the value of `this`.
28+
Keep in mind that if you do not use the `new` keyword the function will **not**
29+
return a new object. While it might still work due to the workings of
30+
[`this`](#how-this-works-in-javascript) in JavaScript, it will use the *global*
31+
object as the value of `this`.
3132

3233
### Factories
3334

‎doc/functions.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
## Functions and statements
1+
## Functions
22

33
Functions in JavaScript are first class objects, which means that they can be
44
passed around like any other value. One common use of this feature is to pass
55
an *anonymous function* as a callback to another, possible asynchronous function.
66

7-
### The `function` statement
7+
### The `function` declaration
88

99
function foo() {}
1010

@@ -26,7 +26,7 @@ The above assigns the unnamed and - *anonymous* - function to the variable `foo`
2626
var foo = function() {};
2727

2828
Due to the fact that `var` is a *statement*, which - just like the function
29-
statement - creates the variable `foo` before the actual execution of the code
29+
declaration - creates the variable `foo` before the actual execution of the code
3030
starts, `foo` is already defined when the script gets executed.
3131

3232
Since assignments only happens at runtime, the value of `Foo` will default
@@ -72,7 +72,7 @@ is due to the lack of block scoping.
7272

7373
### Order of parsing
7474

75-
All `var` statements get parsed **before** `function` statements; hence,
75+
All `var` statements get parsed **before** `function` declartions; hence,
7676
subsequent statements will override the previous ones.
7777

7878
function foo() {}

‎doc/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
- [Objects](#objects)
55
- [The prototype](#prototype)
66
- [`hasOwnProperty`](#hasownproperty)
7-
- [Functions and statements](#functions)
7+
- [Functions](#functions)
88
- [How `this` works](#this)
99
- [Closures and references](#closures)
1010
- [Function arguments](#arguments)

‎doc/objects.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ the use of property names that would otherwise lead to a syntax error.
5959
### Deleting properties
6060

6161
The only way to actually remove a property from an object is to use the `delete`
62-
keyword, setting the property to `undefined` or `null` does **only** remove the
62+
keyword; setting the property to `undefined` or `null` does **only** remove the
6363
value associated with the property, but not the key.
6464

6565
var obj = {
@@ -88,10 +88,12 @@ removed and is therefore missing from the output.
8888
};
8989

9090
Object properties can be both notated as plain characters and as strings. Due to
91-
another mis-design in JavaScript's parser, the above raises a `SyntaxError`.
91+
another mis-design in JavaScript's parser, prior to EcmaScript 5 the above threw
92+
a `SyntaxError`.
9293

9394
This error arises from the fact that `delete` is a *keyword* of the language;
94-
therefore, it must be notated as a string literal.
95+
therefore, it must be notated as a string literal in order to ensure working
96+
code under older JavaScript engines.
9597

9698
[1]: http://en.wikipedia.org/wiki/Hashmap
9799

‎doc/prototype.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ itself has a prototype, the chain goes on with that one afterwards.
9393
### Performance
9494

9595
The lookup time for properties that are high up on the prototype chain can have a
96-
negative impact on performance critical sections of code. Additionally, tying to
96+
negative impact on performance critical sections of code. Additionally, trying to
9797
access non-existent properties will always traverse the full prototype chain.
9898

9999
Also, when [iterating](#the-for-in-loop) over the properties of an object

‎doc/scopes.md‎

Lines changed: 29 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
## Scopes and namespaces
22

3-
Although JavaScript deals fine with the block syntax of two matching curly
4-
braces, it does **not** support block scope; thus, all that is left is the
5-
*function scope*.
3+
Although JavaScript deals fine with the syntax of two matching curly
4+
braces for blocks, it does **not** support block scope; hence, all that is left
5+
is in the language is *function scope*.
66

77
function test() { // a scope
88
for(var i = 0; i < 10; i++) { // not a scope
@@ -11,13 +11,13 @@ braces, it does **not** support block scope; thus, all that is left is the
1111
console.log(i); // 10
1212
}
1313

14-
> **Note:** When not used in an assignment or as a function argument, the `{...}`
15-
> notation will get interpreted as a block statement and **not** as an `Object`.
16-
> This, in conjunction with [automatic insertion of semicolons](#semicolon),
17-
> can lead to subtle errors.
14+
> **Note:** When not used in an assignment, return statement or as a function
15+
> argument, the `{...}` notation will get interpreted as a block statement and
16+
> **not** as an object literal. This, in conjunction with
17+
> [automatic insertion of semicolons](#semicolon), can lead to subtle errors.
1818
19-
Additionally, there are no distinct namespaces in JavaScript. This means that
20-
everything gets defined in **one** globally shared namespace.
19+
There are also no distinct namespaces in JavaScript. This means that everything
20+
gets defined in **one** globally shared namespace.
2121

2222
Each time a variable is referenced, JavaScript will traverse upwards through all
2323
the scopes until it finds it. In the case that it reaches the global scope and
@@ -47,10 +47,10 @@ implications.
4747
test();
4848
foo; // 21
4949

50-
Leaving out the `var` statement will override the value of `foo`, this might not
51-
seem like a big deal at first, but consider having a ten-thousand line
52-
JavaScript file with lots and lots of different variable names, not using `var`
53-
will introduce hard to track down bugs.
50+
Leaving out the `var` statement inside the function `test` will override the
51+
value of `foo`. While this might not seem like a big deal at first, having
52+
thousands of lines of JavaScript and not using `var` will introduce hard to
53+
track down bugs.
5454

5555
// global scope
5656
var items = [/* some list */];
@@ -65,15 +65,15 @@ will introduce hard to track down bugs.
6565
}
6666
}
6767

68-
The outer loop will terminate after the first call to `subLoop` since that
69-
function overwrites the global value of `i`. Using a `var` for the second
70-
`for` loop would have easily avoided this error. The `var` statement should never
71-
be left out unless the desired effect **is** to affect the outer scope.
68+
The outer loop will terminate after the first call to `subLoop`, since `subLoop`
69+
overwrites the global value of `i`. Using a `var` for the second `for` loop would
70+
have easily avoided this error. The `var` statement should never be left out
71+
unless the desired effect **is** to affect the outer scope.
7272

7373
### Local variables
7474

7575
The only source for local variables in JavaScript are [function](#functions)
76-
parameters and variables that were declared with the `var` statement.
76+
parameters and variables that were declared via the `var` statement.
7777

7878
// global scope
7979
var foo = 1;
@@ -90,7 +90,7 @@ parameters and variables that were declared with the `var` statement.
9090
test(10);
9191

9292
While `foo` and `i` are local variables inside the scope of the function `test`,
93-
the assignment of `bar` will override the global variable.
93+
the assignment of `bar` will override the global variable with the same name.
9494

9595
### Name resolution order
9696

@@ -106,16 +106,16 @@ function, JavaScript will lookup the name in the following order:
106106
1. In case there's a `var foo` statement in the current scope use that.
107107
2. If one of the function parameters is named `foo` use that.
108108
3. If the function itself is called `foo` use that.
109-
4. Go to the next outer scope and start from **#1** again.
109+
4. Go to the next outer scope and start with **#1** again.
110110

111111
> **Note:** Having a parameter called `arguments` will **override** the default
112112
> `arguments` object.
113113
114114
### Namespaces
115115

116-
A common problem of having only one global namespace is that it is very easy to
117-
run into problems where variable names clash. But this can be easily avoided
118-
with the help of anonymous *function wrappers*.
116+
A common problem of having only one global namespace is the likeliness of running
117+
into problems where variable names clash. In JavaScript, this problem can be
118+
easily avoided with the help of anonymous *function wrappers*.
119119

120120
(function() {
121121
// a self contained "namespace"
@@ -127,16 +127,15 @@ with the help of anonymous *function wrappers*.
127127
})(); // execute the function immediately
128128

129129

130-
Since a unnamed functions are not considered as [statement](#functions), they
131-
get interpreted as expression, in order to run those functions they must fist be
132-
evaluate and then called.
130+
Unnamed functions are considered [expressions](#functions); so in order to being
131+
callable, they must first be evaluated.
133132

134133
( // evaluate the function inside the paranthesis
135134
function() {}
136135
) // and return the function object
137136
() // call the result of the evaluation
138137

139-
There are other ways for evaluating and calling the function expression; which
138+
There are other ways for evaluating and calling the function expression; which,
140139
while different in syntax, do the exact same thing.
141140

142141
// Two other ways
@@ -146,10 +145,9 @@ while different in syntax, do the exact same thing.
146145
### In conclusion
147146

148147
It is recommended to always use an *anonymous wrapper* for encapsulating code in
149-
its own namespace. This does not only protect against name clashes, but it also
150-
allows for better modularization.
148+
its own namespace. This does not only protect the code against name clashes, it
149+
also allows for better modularization.
151150

152151
Additionally, the use of global variables is considered **bad practice**, any use
153-
of them indicates badly written code that is prone to failure and hard to
154-
maintain.
152+
of them indicates badly written code that is prone to errors and hard to maintain.
155153

‎doc/this.md‎

Lines changed: 7 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -39,20 +39,20 @@ created `Object`.
3939
foo.apply(bar, 1, 2, 3);
4040

4141
When using the `call` or `apply` methods of `Function.prototype`, the value of
42-
`this` inside the called function gets explicitly set to the first arguments of
43-
those function calls.
42+
`this` inside the called function gets explicitly set to the first argument of
43+
the corresponding function call.
4444

4545
In the above example the *method case* does **not** apply, and `this` inside of
4646
`foo` will be set to `bar`.
4747

4848
> **Note:** `this` **cannot** be used to refer to the object inside of an `Object`
4949
> literal. So `var obj = {me: this}` will **not** result in `me` referring to
50-
> `obj`, since `this` gets determined by one of the above cases.
50+
> `obj`, since `this` only gets bound by one of the above five cases.
5151
5252
### Common pitfalls
5353

54-
While most of these cases make sense, the first one is considered a mis-design
55-
by many people as it is **never** of any practical use.
54+
While most of these cases make sense, the first one is to be considered another
55+
mis-design of the language, as it **never** has any practical use.
5656

5757
Foo.method = function() {
5858
function test() {
@@ -64,8 +64,8 @@ by many people as it is **never** of any practical use.
6464
A common misconception is that `this` inside of `test` refers to `Foo`, but it
6565
does **not**.
6666

67-
In order to gain access to `Foo` from within `test` one has to create a local
68-
variable inside of `method` which refers to `Foo`.
67+
In order to gain access to `Foo` from within `test` it is necessary to create a
68+
local variable inside of `method` which refers to `Foo`.
6969

7070
Foo.method = function() {
7171
var that = this;
@@ -104,9 +104,3 @@ makes [prototypical inheritance](#prototype) work.
104104
When `method` gets called on a instance of `Bar`, `this` will now refer to that
105105
instance.
106106

107-
### In conclusion
108-
109-
Understand the exact workings of `this` and **not** trying to work around them is
110-
a requirement for writing efficient and well designed code, that can make use of
111-
features such as [prototypical inheritance](#prototype) and [closures](#closures).
112-

0 commit comments

Comments
 (0)