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

Re: JavaScript/ECMAScript Styling and Citation

From: <jonathan@garbee.me>
Date: Wed, 17 Oct 2012 16:30:42 -0400
To: <public-webplatform@w3.org>
Message-ID: <133b21ab17f617c847b9bd7654322324@garbee.me>
 

I don't think it is being too meticulous at all. We need a common
style guide for any type of code examples we allow that way everything
is consistent. Also, we need them while we are going through cleaning
everything up so we can do that along the way compared to going back and
doing it. It came up in the IRC a few days ago so we decided to use
jQuery's until the community came up with exactly what we would want. So
perhaps taking that and expanding upon it with anything we need extra?


-Garbee 

On 17.10.2012 04:18pm, Pete L. wrote: 

> Not sure if we'd
be creating "yet another style guide" or not. Sure, it's easy to find
"JavaScript style guides", such as the following: 
>
http://docs.jquery.com/JQuery_Core_Style_Guidelines [2] 
>
http://dojotoolkit.org/community/styleGuide [3] 
>
http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml
[4] 
> https://github.com/rwldrn/idiomatic.js [5] 
> However, these
guides are focused on writing re-usable, maintainable, proper production
JavaScript application code. Our goal is somewhat different. For
instance, none of the above guides has anything to say on the subject of
denoting evaluated JS (see my earlier post). 
> Additionally, none of
the guides denote a common set of reusable variable names. For instance,
refer back to the MDN Values, Variables, and Literals page: 
>
https://developer.mozilla.org/en-US/docs/JavaScript/Guide/Values,_variables,_and_literals
[6] 
> The first example uses the variable "answer", the second uses
"x" and "y" then it goes on to use "a", "b", "input", "myArray", "n",
"myvar", "prefix", "f", "g", "coffees", "fish", "myList", "Sales",
"car", "foo", "quote", "home", "str", and then "x" again. My point is
that there isn't even a consistant capitalization style here, much less
a common set of standard variables. I don't know that this really
matters in the long run, but I think it goes towards consistency to use
similar "throwaway variables" across all example code. 
> I guess the
DOJO guide goes into class naming conventions, but it's more oriented
towards substantial code-bases than short snippets of example code. 
>
So, what I'm thinking is not necessarily a style guide that talks about
things like the use of "===" vs. "==", or the use of single-quotes vs.
double-quotes. Those can be addressed by selecting an existing guide
from one of those above (my vote is for jQuery's, as it's short, simple,
and to the point). However, I think that we should supplement with a
guide on variable naming, expression-value commenting, and anything else
we determine should be addressed specifically to bring consistency to
example code. 
> Maybe I'm being a bit to anal-retentive and/or
dictatorial here. 
> -Pete 
> 
> On Wed, Oct 17, 2012 at 11:25 AM, Tobie
Langel <tobie@fb.com [7]> wrote:
> 
>> On 10/17/12 2:28 PM, "Andrew
Rowls" <eternicode@gmail.com [1]> wrote:
>> 
>> >> 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.
>> >
>> >Though
technically unenforceable (for now?), I think it would still be
>>
>beneficial to have official guidelines to point people to. A
discussion
>> >on pros and cons is well and good, but flavor-of-the-week
style in
>> >examples would just be confusing. Better to have a little
official
>> >consistency and something to back it up than to have no
consistency.
>> 
>> Fair enough.
>> 
>> >> I strongly favor vi, here.
>>
>
>> >When did this become about editors? :P
>> 
>> :D
>> 
>> --tobie




Links:
------
[1] mailto:eternicode@gmail.com
[2]
http://docs.jquery.com/JQuery_Core_Style_Guidelines
[3]
http://dojotoolkit.org/community/styleGuide
[4]
http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml
[5]
https://github.com/rwldrn/idiomatic.js
[6]
https://developer.mozilla.org/en-US/docs/JavaScript/Guide/Values,_variables,_and_literals
[7]
mailto:tobie@fb.com
Received on Wednesday, 17 October 2012 20:31:05 UTC

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