Skip to content

Commit 66d98dd

Browse files
committed
[ko] Init files for ko
1 parent 4a93411 commit 66d98dd

24 files changed

+2005
-1
lines changed

doc/ko/array/constructor.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
## The `Array` Constructor
2+
3+
Since the `Array` constructor is ambiguous in how it deals with its parameters,
4+
it is highly recommended to always use the array literals - `[]` notation -
5+
when creating new arrays.
6+
7+
[1, 2, 3]; // Result: [1, 2, 3]
8+
new Array(1, 2, 3); // Result: [1, 2, 3]
9+
10+
[3]; // Result: [3]
11+
new Array(3); // Result: []
12+
new Array('3') // Result: ['3']
13+
14+
In cases when there is only one argument passed to the `Array` constructor
15+
and when that argument is a `Number`, the constructor will return a new *sparse*
16+
array with the `length` property set to the value of the argument. It should be
17+
noted that **only** the `length` property of the new array will be set this way;
18+
the actual indexes of the array will not be initialized.
19+
20+
var arr = new Array(3);
21+
arr[1]; // undefined
22+
1 in arr; // false, the index was not set
23+
24+
The behavior of being able to set the length of the array upfront only comes in
25+
handy in a few cases, like repeating a string, in which it avoids the use of a
26+
`for loop` code.
27+
28+
new Array(count + 1).join(stringToRepeat);
29+
30+
### In Conclusion
31+
32+
The use of the `Array` constructor should be avoided as much as possible.
33+
Literals are definitely preferred. They are shorter and have a clearer syntax;
34+
therefore, they also increase the readability of the code.
35+

doc/ko/array/general.md

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
## Array Iteration and Properties
2+
3+
Although arrays in JavaScript are objects, there are no good reasons to use
4+
the [`for in loop`](#object.forinloop) in for iteration on them. In fact, there
5+
are a number of good reasons **against** the use of `for in` on arrays.
6+
7+
> **Note:** JavaScript arrays are **not** *associative arrays*. JavaScript only
8+
> has [objects](#object.general) for mapping keys to values. And while associative
9+
> arrays **preserve** order, objects **do not**.
10+
11+
Because the `for in` loop enumerates all the properties that are on the prototype
12+
chain and because the only way to exclude those properties is to use
13+
[`hasOwnProperty`](#object.hasownproperty), it is already up to **twenty times**
14+
slower than a normal `for` loop.
15+
16+
### Iteration
17+
18+
In order to achieve the best performance when iterating over arrays, it is best
19+
to use the classic `for` loop.
20+
21+
var list = [1, 2, 3, 4, 5, ...... 100000000];
22+
for(var i = 0, l = list.length; i < l; i++) {
23+
console.log(list[i]);
24+
}
25+
26+
There is one extra catch in the above example, which is the caching of the
27+
length of the array via `l = list.length`.
28+
29+
Although the `length` property is defined on the array itself, there is still an
30+
overhead for doing the lookup on each iteration of the loop. And while recent
31+
JavaScript engines **may** apply optimization in this case, there is no way of
32+
telling whether the code will run on one of these newer engines or not.
33+
34+
In fact, leaving out the caching may result in the loop being only **half as
35+
fast** as with the cached length.
36+
37+
### The `length` Property
38+
39+
While the *getter* of the `length` property simply returns the number of
40+
elements that are contained in the array, the *setter* can be used to
41+
**truncate** the array.
42+
43+
var foo = [1, 2, 3, 4, 5, 6];
44+
foo.length = 3;
45+
foo; // [1, 2, 3]
46+
47+
foo.length = 6;
48+
foo; // [1, 2, 3]
49+
50+
Assigning a smaller length does truncate the array, but increasing the length
51+
does not have any effect on the array.
52+
53+
### In Conclusion
54+
55+
For the best performance, it is recommended to always use the plain `for` loop
56+
and cache the `length` property. The use of `for in` on an array is a sign of
57+
badly written code that is prone to bugs and bad performance.
58+

doc/ko/core/delete.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
## The `delete` Operator
2+
3+
In short, it's *impossible* to delete global variables, functions and some other
4+
stuff in JavaScript which have a `DontDelete` attribute set.
5+
6+
### Global code and Function code
7+
8+
When a variable or a function is defined in a global
9+
or a [function scope](#function.scopes) it is a property of either
10+
Activation object or Global object. Such properties have a set of attributes,
11+
one of these is `DontDelete`. Variable and function declarations in global
12+
and function code always create properties with `DontDelete`, therefore
13+
cannot be deleted.
14+
15+
// global variable:
16+
var a = 1; // DontDelete is set
17+
delete a; // false
18+
a; // 1
19+
20+
// normal function:
21+
function f() {} // DontDelete is set
22+
delete f; // false
23+
typeof f; // "function"
24+
25+
// reassigning doesn't help:
26+
f = 1;
27+
delete f; // false
28+
f; // 1
29+
30+
### Explicit properties
31+
32+
There are things which can be deleted normally: these are explicitly set
33+
properties.
34+
35+
// explicitly set property:
36+
var obj = {x: 1};
37+
obj.y = 2;
38+
delete obj.x; // true
39+
delete obj.y; // true
40+
obj.x; // undefined
41+
obj.y; // undefined
42+
43+
In the example above `obj.x` and `obj.y` can be deleted because they have no
44+
`DontDelete` atribute. That's why an example below works too.
45+
46+
// this works fine, except for IE:
47+
var GLOBAL_OBJECT = this;
48+
GLOBAL_OBJECT.a = 1;
49+
a === GLOBAL_OBJECT.a; // true - just a global var
50+
delete GLOBAL_OBJECT.a; // true
51+
GLOBAL_OBJECT.a; // undefined
52+
53+
Here we use a trick to delete `a`. [`this`](#function.this) here refers
54+
to the Global object and we explicitly declare variable `a` as it's property
55+
which allows us to delete it.
56+
57+
IE (at least 6-8) has some bugs, so code above doesn't work.
58+
59+
### Function arguments and built-ins
60+
61+
Functions' normal arguments, [`arguments` object](#function.arguments)
62+
and built-in properties also have `DontDelete` set.
63+
64+
// function arguments and properties:
65+
(function (x) {
66+
67+
delete arguments; // false
68+
typeof arguments; // "object"
69+
70+
delete x; // false
71+
x; // 1
72+
73+
function f(){}
74+
delete f.length; // false
75+
typeof f.length; // "number"
76+
77+
})(1);
78+
79+
### Host objects
80+
81+
Behaviour of `delete` operator can be unpredictable for hosted objects. Due to
82+
specification, host objects are allowed to implement any kind of behavior.
83+
84+
### In conclusion
85+
86+
`delete` operator often has an unexpected behaviour and can be safely used
87+
only for dealing with explicitly set properties on normal objects.

doc/ko/core/eval.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
## Why Not to Use `eval`
2+
3+
The `eval` function will execute a string of JavaScript code in the local scope.
4+
5+
var foo = 1;
6+
function test() {
7+
var foo = 2;
8+
eval('foo = 3');
9+
return foo;
10+
}
11+
test(); // 3
12+
foo; // 1
13+
14+
However, `eval` only executes in the local scope when it is being called
15+
**directly** *and* when the name of the called function is actually `eval`.
16+
17+
var foo = 1;
18+
function test() {
19+
var foo = 2;
20+
var bar = eval;
21+
bar('foo = 3');
22+
return foo;
23+
}
24+
test(); // 2
25+
foo; // 3
26+
27+
The use of `eval` should be avoided at **all costs**. 99.9% of its "uses" can be
28+
achieved **without** it.
29+
30+
### `eval` in Disguise
31+
32+
The [timeout functions](#other.timeouts) `setTimeout` and `setInterval` can both
33+
take a string as their first argument. This string will **always** get executed
34+
in the global scope since `eval` is not being called directly in that case.
35+
36+
### Security Issues
37+
38+
`eval` also is a security problem. Because it executes **any** code given to it,
39+
it should **never** be used with strings of unknown or untrusted origins.
40+
41+
### In Conclusion
42+
43+
`eval` should never be used. Any code that makes use of it is to be questioned in
44+
its workings, performance and security. In case something requires `eval` in
45+
order to work, it should **not** be used in the first place.
46+
A *better design* should be used, that does not require the use of `eval`.
47+

doc/ko/core/semicolon.md

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
## Automatic Semicolon Insertion
2+
3+
Although JavaScript has C style syntax, it does **not** enforce the use of
4+
semicolons in the source code, so it is possible to omit them.
5+
6+
JavaScript is not a semicolon-less language. In fact, it needs the
7+
semicolons in order to understand the source code. Therefore, the JavaScript
8+
parser **automatically** inserts them whenever it encounters a parse
9+
error due to a missing semicolon.
10+
11+
var foo = function() {
12+
} // parse error, semicolon expected
13+
test()
14+
15+
Insertion happens, and the parser tries again.
16+
17+
var foo = function() {
18+
}; // no error, parser continues
19+
test()
20+
21+
The automatic insertion of semicolon is considered to be one of **biggest**
22+
design flaws in the language because it *can* change the behavior of code.
23+
24+
### How it Works
25+
26+
The code below has no semicolons in it, so it is up to the parser to decide where
27+
to insert them.
28+
29+
(function(window, undefined) {
30+
function test(options) {
31+
log('testing!')
32+
33+
(options.list || []).forEach(function(i) {
34+
35+
})
36+
37+
options.value.test(
38+
'long string to pass here',
39+
'and another long string to pass'
40+
)
41+
42+
return
43+
{
44+
foo: function() {}
45+
}
46+
}
47+
window.test = test
48+
49+
})(window)
50+
51+
(function(window) {
52+
window.someLibrary = {}
53+
54+
})(window)
55+
56+
Below is the result of the parser's "guessing" game.
57+
58+
(function(window, undefined) {
59+
function test(options) {
60+
61+
// Not inserted, lines got merged
62+
log('testing!')(options.list || []).forEach(function(i) {
63+
64+
}); // <- inserted
65+
66+
options.value.test(
67+
'long string to pass here',
68+
'and another long string to pass'
69+
); // <- inserted
70+
71+
return; // <- inserted, breaks the return statement
72+
{ // treated as a block
73+
74+
// a label and a single expression statement
75+
foo: function() {}
76+
}; // <- inserted
77+
}
78+
window.test = test; // <- inserted
79+
80+
// The lines got merged again
81+
})(window)(function(window) {
82+
window.someLibrary = {}; // <- inserted
83+
84+
})(window); //<- inserted
85+
86+
> **Note:** The JavaScript parser does not "correctly" handle return statements
87+
> which are followed by a new line, while this is not neccessarily the fault of
88+
> the automatic semicolon insertion, it can still be an unwanted side-effect.
89+
90+
The parser drastically changed the behavior of the code above. In certain cases,
91+
it does the **wrong thing**.
92+
93+
### Leading Parenthesis
94+
95+
In case of a leading parenthesis, the parser will **not** insert a semicolon.
96+
97+
log('testing!')
98+
(options.list || []).forEach(function(i) {})
99+
100+
This code gets transformed into one line.
101+
102+
log('testing!')(options.list || []).forEach(function(i) {})
103+
104+
Chances are **very** high that `log` does **not** return a function; therefore,
105+
the above will yield a `TypeError` stating that `undefined is not a function`.
106+
107+
### In Conclusion
108+
109+
It is highly recommended to **never** omit semicolons; it is also advocated to
110+
keep braces on the same line with their corresponding statements and to never omit
111+
them for one single-line `if` / `else` statements. Both of these measures will
112+
not only improve the consistency of the code, but they will also prevent the
113+
JavaScript parser from changing its behavior.
114+

0 commit comments

Comments
 (0)