Re: JavaScript/ECMAScript Styling and Citation

On Oct 16, 2012, at 21:54, "Pete L." <plamoni@gmail.com<mailto:plamoni@gmail.com>> wrote:

1: Citations -
It seems appropriate that we offer up references to the applicable ECMAScript specification when discussing a language feature. However, unlike with W3C standards, the ECMAScript standard officially comes packaged as one big PDF. Normally, when I cite ECMAScript standards in my JS teaching, I use http://es5.github.com/ for ES5 and http://bclary.com/2004/11/07/ for ES3 (both allow simple direct-links to individual sections). However, these are not the official specifications (they're maintained by third parties). So I was wondering how we wanted to approach ECMAScript citations?

ECMAScript 5.1 now has an official HTML version: http://ecma-international.org/ecma-262/5.1/

2: JavaScript "versions" -
A large amount of our JavaScript material is sourced from MDN, which promotes the use of Mozilla's proprietary JavaScript "Versions" (1.4, 1.5, etc.). These versions are not recognized as standards and are specific to Mozilla's browsers. Per the Getting Started guide, we should avoid (or at least denote) vendor-specific nomenclature like this. So I assume we should strip out or try to universalize these references when we see them?

+1 for stripping those out.

3: JavaScript coding style -
We had a short discussion in the IRC chat about this yesterday and the general consensus seemed to be that jQuery's coding style guidelines would be a good start for JavaScript coding style (http://docs.jquery.com/JQuery_Core_Style_Guidelines). It works for me, but maybe we want to create something specific for WPD.

I would go with Dojo's but that's purely subjective. TBH, It's unenforceable unless there's proper tooling. I'd leave it open and have a page discussing the various styles pros and cons.

4: Denoting expression values -
JavaScript references are always denoting the value of an expression in one way or another. However, I can't find a single book in my library that creates a standard formatting for the task (though often they settle on one or another).. MDN is terrible when it comes to this (see below). Personally, I'm a fan of using the following syntax:

var a = 4;
a + 1; //is 5

However, I've seen other forms that seem to be more or less valid, such as:

i) a + 1; //returns 5
ii) a + 1; // 5
iii) console.log(a + 1); //prints 5
iv) document.write(a + 1); //prints 5
v) a + 1 = 5
vi) a + 1; //=> 5

There are plenty more, but that's a general sampling. Version (ii) and a modified version (iv) are used regularly in Crockford's "JavaScript: The Good Parts", while "JavaScript: The Definitive Guide" mostly uses (iii). John Resig's "Pro JavaScript Techniques" uses a combination of detailed, descriptive comments and alert()'s (which I think is dreadful). MDN doesn't seem to be able to pick one and uses a combination of (iii), (iv), and the syntactic atrocity that is (v). I've also seen (vi) used somewhere, but I can't seem to figure out where (I like it, though). While (iii) seems to be the most widely-used version, I don't like it because the console object is not defined in older versions of IE unless the developer tools are open. So IE<=8(?) users will end up getting errors if the developer accidentally leaves a console.log() in their code.

I strongly favor vi, here.

--tobie