diff --git a/src/docs/book/flavor.book b/src/docs/book/flavor.book index 4404e94bf7..c9a80fae92 100644 --- a/src/docs/book/flavor.book +++ b/src/docs/book/flavor.book @@ -21,7 +21,7 @@ ], "groups": { "javascript": { - "name": "Javascript" + "name": "JavaScript" }, "lore": { "name": "Phorge Lore" diff --git a/src/docs/flavor/javascript_object_array.diviner b/src/docs/flavor/javascript_object_array.diviner index cdba029e9a..113dbb1000 100644 --- a/src/docs/flavor/javascript_object_array.diviner +++ b/src/docs/flavor/javascript_object_array.diviner @@ -1,13 +1,13 @@ -@title Javascript Object and Array +@title JavaScript Object and Array @group javascript -This document describes the behaviors of Object and Array in Javascript, and +This document describes the behaviors of Object and Array in JavaScript, and a specific approach to their use which produces basically reasonable language behavior. = Primitives = -Javascript has two native datatype primitives, Object and Array. Both are +JavaScript has two native datatype primitives, Object and Array. Both are classes, so you can use `new` to instantiate new objects and arrays: COUNTEREXAMPLE @@ -43,11 +43,11 @@ and Array are both classes, but "object" is also a primitive type. Object is = Objects are Maps, Arrays are Lists = PHP has a single `array` datatype which behaves like as both map and a list, -and a common mistake is to treat Javascript arrays (or objects) in the same way. +and a common mistake is to treat JavaScript arrays (or objects) in the same way. **Don't do this.** It sort of works until it doesn't. Instead, learn how -Javascript's native datatypes work and use them properly. +JavaScript's native datatypes work and use them properly. -In Javascript, you should think of Objects as maps ("dictionaries") and Arrays +In JavaScript, you should think of Objects as maps ("dictionaries") and Arrays as lists ("vectors"). You store keys-value pairs in a map, and store ordered values in a list. So, @@ -58,7 +58,13 @@ store key-value pairs in Objects. species: 'zebra' }; - console.log(o.name); + o.paws = 4; + + o['numberOfEars'] = 2; + + console.log(o.name); + console.log(o.paws); + console.log(o.numberOfEars); ...and store ordered values in Arrays. @@ -71,8 +77,14 @@ Don't store key-value pairs in Arrays and don't expect Objects to be ordered. var a = []; a['name'] = 'Hubert'; // No! Don't do this! -This technically works because Arrays are Objects and you think everything is -fine and dandy, but it won't do what you want and will burn you. +Technically, both work because Arrays //are// Objects and you think everything +is fine and dandy, but it won't do what you want and will burn you. For example, +using `.length` will play tricks on you. + +In short, trust me: + +* use `[]` only to create a stack of consecutive elements numerically indexed +* use `{}` to create associative maps ("associative arrays") = Iterating over Maps and Lists = @@ -140,7 +152,7 @@ The correct way to deal with this is: continue; } f(list[ii]); - } + } Avoid sparse arrays if possible. diff --git a/src/docs/flavor/javascript_pitfalls.diviner b/src/docs/flavor/javascript_pitfalls.diviner index 9276ae4712..fbc2eae05c 100644 --- a/src/docs/flavor/javascript_pitfalls.diviner +++ b/src/docs/flavor/javascript_pitfalls.diviner @@ -1,12 +1,12 @@ -@title Javascript Pitfalls +@title JavaScript Pitfalls @group javascript -This document discusses pitfalls and flaws in the Javascript language, and how +This document discusses pitfalls and flaws in the JavaScript language, and how to avoid, work around, or at least understand them. = Implicit Semicolons = -Javascript tries to insert semicolons if you forgot them. This is a pretty +JavaScript tries to insert semicolons if you forgot them. This is a pretty horrible idea. Notably, it can mask syntax errors by transforming subexpressions on their own lines into statements with no effect: @@ -46,11 +46,11 @@ you can pass `arguments` to Function.prototype.apply() without converting it. There is essentially only one reasonable, consistent way to use these primitives but it is not obvious. Navigate these troubled waters with -@{article:Javascript Object and Array}. +@{article:JavaScript Object and Array}. = typeof null == "object" = -This statement is true in Javascript: +This statement is true in JavaScript: typeof null == 'object' @@ -58,9 +58,9 @@ This is pretty much a bug in the language that can never be fixed now. = Number, String, and Boolean objects = -Like Java, Javascript has primitive versions of number, string, and boolean, +Like Java, JavaScript has primitive versions of number, string, and boolean, and object versions. In Java, there's some argument for this distinction. In -Javascript, it's pretty much completely worthless and the behavior of these +JavaScript, it's pretty much completely worthless and the behavior of these objects is wrong. String and Boolean in particular are essentially unusable: lang=js @@ -83,5 +83,5 @@ Number.prototype, etc.) and their logical behavior is at best absurd and at worst strictly wrong. **Never use** `new Number()`, `new String()` or `new Boolean()` unless -your Javascript is God Tier and you are absolutely sure you know what you are +your JavaScript is God Tier and you are absolutely sure you know what you are doing. diff --git a/src/docs/flavor/php_pitfalls.diviner b/src/docs/flavor/php_pitfalls.diviner index 3f4be45dd7..e15ca9e2bb 100644 --- a/src/docs/flavor/php_pitfalls.diviner +++ b/src/docs/flavor/php_pitfalls.diviner @@ -256,7 +256,7 @@ echo $obj->flavor; // Outputs 'coconut'. echo get_class($obj); // Outputs 'stdClass'. ``` -This is occasionally useful, mostly to force an object to become a Javascript +This is occasionally useful, mostly to force an object to become a JavaScript dictionary (vs a list) when passed to `json_encode()`. = Invoking `new` With an Argument Vector is Really Hard = diff --git a/src/docs/flavor/project_history.diviner b/src/docs/flavor/project_history.diviner index 1159304cda..6b51e203ed 100644 --- a/src/docs/flavor/project_history.diviner +++ b/src/docs/flavor/project_history.diviner @@ -34,7 +34,7 @@ it also gained a lot of performance problems, usability issues, and bugs. Through 2007 and 2008 Evan worked mostly on frontend and support infrastructure; among other things, he wrote a static resource management system called Haste. In 2009 Evan worked on the Facebook Lite site, where he built the Javelin -Javascript library and an MVC-flavored framework called Alite. +JavaScript library and an MVC-flavored framework called Alite. But by early 2010, Diffcamp was in pretty bad shape. Two years of having random features grafted onto it without real direction had left it slow and difficult