Proposal for policy change regarding use of ES6 features in code examples

MDN
#1

Hi all,

As I work on a plan for a new set of MDN code guidelines, one issue that has come up is our policy on use of modern JavaScript features. So far we have avoided using ES6+ features as much as possible, as we felt that a lot of web developers don’t use them yet, so they will just serve to make examples less understandable, raising the barrier for comprehension unnecessarily.

Our feelings on this have never been officially recorded anywhere, except for the Interactive example JS guidelines. I intend to change that by giving an official recommendation in the guidelines.

But I also wanted to make the case that we move with the times, and start using ES6+ features on MDN examples. I think since we decided our existing policy, things have moved on, and developers are now comfortable with more modern JS features than they used to be.

I think our new recommendation should be something like:

"For general usage*, we are fine with common ES6 features being used in MDN examples, such as arrow functions, promises, let/const, template literals, and spread syntax. For newer features like async/await, trailing commas on argument lists, maps, etc., we’d prefer you not to use those unless strictly necessary, and if you do use them, include explanation in your example to say what they are doing, with a link to appropriate reference material.

* as in, general example writing. Reference pages covering specific modern ES features obviously need to use the features they are documenting!"

What do people feel about this?

1 Like
#2

This sounds like a perfect case where a little user research can make a big difference. Not regarding the fact that ES6 is where we should go, but what part of the community ready for that, and maybe to get pointers about how to go about that? It seems like a pretty big change.

2 Likes
#3

I am very much in favour of preferring usage of ES6+ features in examples (at least preferring let and const over var, because var is riddled with footguns).

#4

Definitely in favor of generally transitioning to using let. I am not sure I feel the same way about arrow functions, as I still find them very hard to read because of their brevity and the specifics of the syntax that make it… I don’t know… almost too concise.

#5

Of course Kadir’s right that we should have data on this.

But this is also a policy question for us: we shouldn’t just reflect the current understanding of developers but should try to advance it. If people don’t know about new features, so we don’t publicise them, then they will never learn. I learned about these features because people started using them, so I had to.

2 Likes
#6

This is a really good point Will.

I’m still intending to do some research on this, but I really think we should raise the bar to ES6 for this kind of reason.

In the research, I think I’m going to ask developers about their understanding of multiple levels of ES stuff — 6 and beyond.

1 Like
#7

All true. Using new features of the langugae does
But we must make sure that the code we post on MDN is clearly readable; some of the amazingly useful shortcuts and syntax features now available can obfuscate samples.

1 Like
#8

Hi All,

I’m totally new to the community so maybe there is an answer to my question I just didn’t find it. I teach JavaScript and I always encourage the students to use let and const over var however, they still find many var declarations on MDN. I suggest them learning from MDN because it is up to date and extensive. Now I am a bit confused when they ask why is MDN full of var-s. I would be happy to start replacing all the vars (of course except where the documentation is about ES5 or earlier) but I don’t know if they are there for a purpose or not.
Now I’ve found this discussion, are there any update @chrisdavidmills?
Can I just edit the pages that I find or do you have any defined process to make such changes?

1 Like
#9

This is something I’d love to do, but there are so many pages to change, and so little time. Our updated policy does actually state to use ES6 features on all new pages: https://developer.mozilla.org/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/JavaScript#Use_ES6_features

I can only suggest that you replace old-style syntax as you find it.

1 Like
#10

Thank you :slight_smile: That was my plan, I browse mdn a lot so I will update what I find. Thanks again

3 Likes
#11

@ikarasz filed https://github.com/mdn/interactive-examples/pull/1470 to update some interactive examples to use let/const instead of var. Thanks!

One thing that came out of that was that we don’t have any guidance for when to use const and when to use let. So I’ve updated our guidelines to be explicit here, and Florian’s reviewed it.

3 Likes