JS examples: style guide

MDN
#1

This came up through the work Mark’s doing to add interactive examples to the JS pages. It would be good to have a style guide for JS examples on MDN - not just in the interactive examples, but in all example code.

The question is: which one? I know the AirBnb one has a good reputation, but it’s ES6-y.

Whether we should start using ES6-y things in the JS examples is a bigger question, and perhaps one we should address first. I know we discussed this a while back: https://groups.google.com/forum/#!topic/mozilla.dev.mdc/ssw4AeqJKQY and decided not to, but this is probably a conversation we should have at regular intervals :). Or should we look into supporting both variants?

1 Like
Policy on modern JavaScript?
#2

I agree that we need a style guide.

As for ES6 stuff, my opinion is that we should avoid ES6 constructs like arrow functions and the like for the first example or two in an article, then introduce the more advanced syntax if we wish to do so and it’s appropriate. That way, we cover all the angles and we avoid hitting potential ES6 newbies with syntax they won’t recognize or understand.

Sheppy

#3

We do already have this:

But it probably needs an update (there are a couple of bits in the JS stuff that I know we don’t follow, and we don’t mention the ES5 vs ES6 situation).

As time goes on, I am getting more used to the idea of ES6 code in examples, but I think I like sheppy’s line of thinking here. Provided the doc we are talking about would suit an ES6 syntax example, and isn’t itself documenting a ES6 feature, I’d go for something like:

  1. Include a basic example that uses ES5.

  2. Include a slightly more advanced/real world example that uses ES6.

  3. Link to the documentation we have available on ES6 features (as we’ve said before, a guide to converting between ES5 and ES6 would be really useful)

#4

We do already have this:

Sorry, yes, I did find that. But it doesn’t answer even the most basic questions someone might have. Single or double quotes? Braces around single-line if blocks? 2 or 4 space indentation?

I’d go for something like…

I like that this acknowledges that these features are out there, but I’m not sure if it goes far enough. I really liked Mark’s idea to have “ES6 mode” in examples, although we can only do that for the interactive examples.

Maybe we should have a survey on MDN asking people (1) if they use specific features in their work and (2) if they would prefer the examples to use those features?

#5

We follow the Mozilla coding style guide in our examples, officially, and have since forever ago (that’s what the rule was when I joined the team in 2006). We should be more explicit about that, I suppose, in our meta documentation.

I am on the fence about what to do about ES6 use in examples. I’m largely opposed to using any more concepts than necessary in a given example. Even though the code may be a bit more involved using ES5, I think it’s wise for now to at least introduce concepts using ES5 code before adding ES6 constructs into the mix, whenever possible. For example, I would avoid using arrow functions in the initial examples for a tech; instead, I’d use ES5 for the first example that introduces the technology, then opt to use ES6 as appropriate in later examples, perhaps.

That said, of course, over time the ES6 stuff will become more “mainstream” and we won’t have to worry about it as much.

I do like the idea of a survey about this stuff. Ask about specific technologies and tech areas, including promises and arrow functions and the like, and get a feel for how much we can use those without confusing people.

Eric Shepherd
Senior Technical Writer
MDN Web Docs: https://developer.mozilla.org/
Blog: http://www.bitstampede.com/
Twitter: http://twitter.com/sheppy