W3C home > Mailing lists > Public > public-webplatform@w3.org > October 2012

JavaScript/ECMAScript Styling and Citation

From: Pete L. <plamoni@gmail.com>
Date: Tue, 16 Oct 2012 10:24:11 -0500
Message-ID: <CADRHs0j+sN36X8btnfcYC3MM6pmM225Jq_dJpdNkQ_-1TVm0Dw@mail.gmail.com>
To: "WebPlatform.org" <public-webplatform@w3.org>
I was going through and looking to do some cleanup on JavaScript, and I
came up with some questions that need to be addressed (if they haven't been
already):

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?

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?

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.

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'd love to get feedback on these from the real JS experts in the group.

-Pete
Received on Tuesday, 16 October 2012 19:53:50 UTC

This archive was generated by hypermail 2.3.1 : Wednesday, 8 May 2013 19:57:34 UTC