const and arrow functions (and other ES6+ -isms) in code samples

[David Bruant]

Hi,

I teach JavaScript to beginners and in doing so, MDN is obviously a
resource of choice. But I've recently had a dilemma I'd like to share
here both for the pedagological perspective and the changes that may
need to be reflected on MDN.

I teach beginners in JS, but also beginners in programming for whom
JavaScript is the first language. Also, more often than not, these
people need to ship the code they write to older browsers (IE8-9, old
webkit-based browsers, etc.). As a consequence, every time I see them
copy/paste code from MDN which is ES6+ (as in [1]), I end up telling
them to write it differently, otherwise their code won't work on older
browsers at all (all new syntax triggers a SyntaxError in older
browsers). I'm aware of this, but it is not obvious for beginners to
know which syntax is safe and which isn't.

One solution could be to direct the learners to solution like babel
(translates future ECMAScript to current ECMAScript), but they also
often are not familiar to the command line, so it doesn't feel
appropriate and is one more thing to learn that distracts them from
writing/learning "just javascript".

My first question is on the pedagogy side :

Do other teachers make different trade-offs when it comes to teaching
JavaScript to beginners when it comes to ES6+?

My other question is about MDN itself. I haven't seen this discussed in
the guidelines [2] :

Should MDN code samples be written in ES5? (besides of course for the
documentation of ES6+ syntax features)

Thanks,

David

[1]
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all#Using_Promise.all

[2]
https://developer.mozilla.org/en-US/docs/MDN/Contribute/Guidelines/Code_samples#JavaScript

[Sebastian Zartner]

On 20 November 2016 at 14:36, David Bruant <brua...@gmail.com> wrote:
> My other question is about MDN itself. I haven't seen this discussed in the
> guidelines [2] :
>
> Should MDN code samples be written in ES5? (besides of course for the
> documentation of ES6+ syntax features)

Good question! I'd say they should be written in ES5, so they can be
used in most browsers.
Which standard to use should also be outlined in the style guide.

Sebastian

[Anthony Maton]

IMHO using ES5 is not inciting people to evolve it's like learning HTML4
because HTML5 is not fully implemented.

If they need implementation for browsers coming from the middle age, they
should probably read the specific bit of ES5 they need or use babel.

Le 20 nov. 2016 10:00 PM, "Sebastian Zartner" <sebastia...@gmail.com>
a écrit :

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide
>

[Sebastian Zartner]

Let me revisit my answer. What I meant is, if the majority of users in
the world still use browsers that can't handle ES6+, then the examples
should still be written in ES5. If most browsers support ES6+, let's
create examples in using the newer standards.

Sebastian

[Chris Mills]

This is a slightly tricky call. When I started writing the Learning Area JavaScript tutorials[0], I stuck to ES5 purely for simplicity’s sake. I know that some of my readers use slightly older browsers (like IE9 or 10) for running through the course, and I wanted to minimize the risk of stuff not working for them, as well as maximizing the likelihood of them understanding the stuff they meet in the wild.

I certainly didn’t want to have to say ummmm, this stuff won’t work in older browsers, let’s set up babel before we start to learn JavaScript.

But I appreciate this is a slightly different case to MDN docs in general. I think in places where there is an ES5 version and some newer syntatic sugar to discuss, both should be shown, or at least the other one should be linked to.

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

[0] https://developer.mozilla.org/en-US/docs/Learn/JavaScript

[Chris Mills]

> On 21 Nov 2016, at 06:22, Chris Mills <cmi...@mozilla.com> wrote:
>
> This is a slightly tricky call. When I started writing the Learning Area JavaScript tutorials[0], I stuck to ES5 purely for simplicity’s sake. I know that some of my readers use slightly older browsers (like IE9 or 10) for running through the course, and I wanted to minimize the risk of stuff not working for them, as well as maximizing the likelihood of them understanding the stuff they meet in the wild.

To be clear, this is the same reason why we shouldn’t just show beginners examples written in jQuery, or some other library.

[David Bruant]

Le 20/11/2016 à 22:46, Anthony Maton a écrit :
>
> IMHO using ES5 is not inciting people to evolve it's like learning
> HTML4 because HTML5 is not fully implemented.
>

"evolving" is not my major concern here. As a matter of personal taste,
I hope everyone will move to ES6 syntax and know it will eventually
happen eventually. My concern is the short term as well as not
discouraging beginners.
The comparison with "HTML4" is inappropriate in the sense that older
browsers do render something anyway if they don't understand an element
or ignore HTML attributes they don't understand. This is not the case
for JavaScript syntax which only offers an all-or-nothing approach to
whether the code will run which is a fairly aggressive fallback.

> If they need implementation for browsers coming from the middle age,
> they should probably read the specific bit of ES5 they need or use babel.
>

I don't think it can be expected from people who are beginners in JS to
verify whether every code sample they find on MDN is ES6 or not.
For beginners, JavaScript is already hard enough in and of itself, I'd
like to reduce the burden.

When it comes to babel, as I said, some folks either don't know or
aren't comfortable with the commandline.
That said, it might be a reasonable thing to tell beginners that the
code they copy/paste works in current browsers as is, but will require a
tool like babel if they want to run it in older browsers. Maybe it's a
reasonable constraints to say that if they want old browser support,
they need to put additional work. I don't know. I'm really torn.

Especially for Promise examples. Although arrow functions are super
nice, Promise are now a core JS primitive (because of being a core
concept of async programming) and can be used today in all browsers
because polyfills exist.
(sorry, i'm babling/writing-as-i'm-thinking)

David

>
> Le 20 nov. 2016 10:00 PM, "Sebastian Zartner"

> <sebastia...@gmail.com <mailto:sebastia...@gmail.com>> a écrit :

>
> On 20 November 2016 at 14:36, David Bruant <brua...@gmail.com

> <mailto:brua...@gmail.com>> wrote:
> > My other question is about MDN itself. I haven't seen this
> discussed in the
> > guidelines [2] :
> >
> > Should MDN code samples be written in ES5? (besides of course
> for the
> > documentation of ES6+ syntax features)
>
> Good question! I'd say they should be written in ES5, so they can be
> used in most browsers.
> Which standard to use should also be outlined in the style guide.
>
> Sebastian
> _______________________________________________
> dev-mdc mailing list

> dev...@lists.mozilla.org <mailto:dev...@lists.mozilla.org>
> https://lists.mozilla.org/listinfo/dev-mdc

[Florian Scholz]

My rules of thumb:

- Don't use new features (ES6, ESdraft, Fetch, anything "new") if not
necessary for understanding $thing. Destructuring, arrow functions and
friends are clever but readability can suffer. New features like Fetch
on the other hand might be easier to learn than XHR, but I think it
needs to come with a heads up about its compatibility.

– If it makes sense, show both:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every#Examples

Compatibility will always be a topic. ES6 is a bit special here because
it is a big bulk of features, but things move on already. So while we
ask today if ES5 or ES6, I think it wont be as easy as choosing between
these two in say late 2017. Should we be using async/await syntax
instead of just promises? Not if not necessary I guess. We are also not
using class syntax for larger tutorials etc. Of course this all depends
also on context, so I think it might be hard to come up with definite
rules here.

I think MDN has been good at showing what the pure web platform can do
in a highly compatible way, without jQuery and libraries, and without
babel and transpilers. We do have polyfills on a lot of pages and we
offer compat tables and notes for when something is still unstable and
not widely implemented to help with the compatibility issues people come
across.

But maybe we can come up with new ideas of how examples work and "talk"
to readers about their compatibility when we think that we want to use
certain new features from a teaching perspective.

Like a warning shown when a page is read with a browser that doesn't
support the mentioned features or using more data in a similar way
caniuse.com answers the question.

Or, once we have nodejs compat data, you might want to add your current
project's nodejs version to your MDN profile, and we will give warnings
whenever that version doesn't include a certain feature. It is certainly
easier with a versioned environment, but learners also have to
understand the versionless compatibility world of the web as they learn
about new features :-)

(also thinking as I'm writing)
Florian

Florian Scholz
Technical Writer
Mozilla Developer Network

[Janet Swisher]

On 11/21/16 5:39, David Bruant wrote:
> I don't think it can be expected from people who are beginners in JS
> to verify whether every code sample they find on MDN is ES6 or not.
> For beginners, JavaScript is already hard enough in and of itself, I'd
> like to reduce the burden.
>
> When it comes to babel, as I said, some folks either don't know or
> aren't comfortable with the commandline.
> That said, it might be a reasonable thing to tell beginners that the
> code they copy/paste works in current browsers as is, but will require
> a tool like babel if they want to run it in older browsers. Maybe it's
> a reasonable constraints to say that if they want old browser support,
> they need to put additional work.

From a pedagogy standpoint, I think it's reasonable to pick one
version, and to treat the other as an "advanced topic". In the interest
of providing students with future-oriented skills, you can say "This
course covers writing JavaScript for modern browsers; writing JavaScript
for older browsers is an advanced topic that you will be equipped to
master *after* you've finished this course." Don't try to do both, and
set the expectation ahead of time that there is some complexity you're
avoiding in favor of clarity. (This also gives you the opportunity to
offer a second course :-)

P.S. Hi David! It's nice to hear from you!


--

Janet Swisher <mailto:jREMOVE...@mozilla.com>
Mozilla Developer Network <https://developer.mozilla.org>
Community Strategist

[Joe Medley]

"I think MDN has been good at showing what the pure web platform can do
in a highly compatible way, without jQuery and libraries, and without
babel and transpilers."

In response to this and other comments I went looking for an MDN mission statement. I didn't find one, but I did notice this on the front page:

"Shared knowledge for the Open Web"

Emphasis on 'Open Web'. This is the whole reason my employer pays me to contribute to this site. If that is indeed the mission of this site, it argues for holding off on the general use of ES6 features until supporting browsers are broadly distributed in the ecosystem.

[Janet Swisher]

On 11/21/16 13:07, Joe Medley wrote:
> "I think MDN has been good at showing what the pure web platform can do
> in a highly compatible way, without jQuery and libraries, and without
> babel and transpilers."
>

> In response to this and other comments I went looking for an MDN mission statement. I didn't find one, but I did notice this on the front page:
>
> "Shared knowledge for the Open Web"
>
> Emphasis on 'Open Web'. This is the whole reason my employer pays me to contribute to this site.
>

Thanks for pointing out that findability gap. Here are two places where
you can find MDN's mission statement:

https://developer.mozilla.org/en-US/docs/MDN/About
https://wiki.mozilla.org/MDN/

[Stephanie Hobson]

ES5 allows our site to be delivered without pollyfills or transpilers which
makes my life easier. As a developer working on a site that does not use
ES6. I would prefer ES5 examples ;)

The ES5 examples can be copy/pasted into an ES6 environment and still work.
The reverse is not true.

S.

On Mon, Nov 21, 2016 at 10:07 AM, Joe Medley <jme...@google.com> wrote:

> "I think MDN has been good at showing what the pure web platform can do
> in a highly compatible way, without jQuery and libraries, and without
> babel and transpilers."
>

> In response to this and other comments I went looking for an MDN mission
> statement. I didn't find one, but I did notice this on the front page:
>
> "Shared knowledge for the Open Web"
>
> Emphasis on 'Open Web'. This is the whole reason my employer pays me to

> contribute to this site. If that is indeed the mission of this site, it
> argues for holding off on the general use of ES6 features until supporting
> browsers are broadly distributed in the ecosystem.

[DL Neil]

(with apologies for mis-addressing)

Dear Sebastian (and you gentle reader!)

On 21/11/16 11:12, Sebastian Zartner wrote:
> Let me revisit my answer. What I meant is, if the majority of users in
> the world still use browsers that can't handle ES6+, then the examples
> should still be written in ES5. If most browsers support ES6+, let's
> create examples in using the newer standards.
>
> Sebastian
>
> On 20 November 2016 at 22:46, Anthony Maton <maitr...@gmail.com> wrote:

>> IMHO using ES5 is not inciting people to evolve it's like learning HTML4
>> because HTML5 is not fully implemented.
>>

>> Le 20 nov. 2016 10:00 PM, "Sebastian Zartner" <sebastia...@gmail.com> a

>> écrit :
>>>
>>> On 20 November 2016 at 14:36, David Bruant <brua...@gmail.com> wrote:
>>> Good question! I'd say they should be written in ES5, so they can be
>>> used in most browsers.
>>> Which standard to use should also be outlined in the style guide.

Is the solution to inform the user of the 'age' of each syntactic
element, and empower the reader to make his/her own decision to utilise?
(age or "pre-requisites")


As a fellow trainer, I wonder if we focus on MDN's content from a
particular direction? - but are there are other views and purposes!

A training course for complete beginners will use MDN is one mode. A
course introducing JS to computer programmers, in a slightly different
way. An update course for JS coders moving to ES6 (or ES5!), will employ
quite a different approach again. Plus, someone not in training
(per-se), working 'at the coal face', will value MDN for its look-up and
'reminder' facility. (etc)


Another view, is not so much when the information should be presented to
MDN users, but when MDN authors are able, prepared, and motivated to
assemble their thoughts and put them down 'on paper'. Is documentation
part of the design and development process(es) or something separate to
be done 'later'?


Additionally, there is the dimension that the tools our learners (and
web-app users) may or may not support certain features of 'the'
language. This worsens when we consider that many large enterprises, to
say nothing of so many in the developing world, are still using WinXP
and with the best will in the world, cannot upgrade to 'the latest'.

Similarly, considering the mobile community, we rapidly find that
smaller devices and slower connections reduce the range of viable
constructs.


Should the limits of these various sub-communities proscribe the
boundaries for all?


Looking at MDN's HTML entries, towards the end of most pages there is a
summary of browser support. Additionally, one of the most valuable aids
in my training has to be CanIUse.com which conveys similar information,
and both more - and less.

This is necessary because there are HTML5 elements which are covered in
one/some browsers and not in others (eg choice of VTT tracks for video,
video file encoding options, ...), as well as the issue that its
coverage may have a short history.

We warn of such 'gotchas' in our courseware - to the extent of stating
that a particular module's content may only be possible using certain
browsers and then offering examples and inviting coding which may only
be viewed/tested therein (with video content and/or static images or
code listings for those unable to follow otherwise).


Might we (trainers) be doing other users of MDN a disservice by asking
that all materials be prepared (only) with the complete beginner in mind?

Should MDN be encouraging the use of the latest (or at least, 'modern')
browsers (and quite possibly favoring that Mozilla Firefox, even FFDE,
'thingy')?

How will 'the wider community' learn to employ new >ES6 and >HTML5
Nov2016 'versions', if materials are not published on MDN until 'later'?
(to say nothing of, define "later")

What author/reader tools and tactics might enable MDN to meet the needs
of every, or at least the widest variety of, developer?


but to finish with a non-Socratic statement (which agrees with your
primary sentiment): MDN should always be written to encourage continual
learning (and the usage of Firefox)!


--
Regards,
=dn

[Eric Shepherd]

I agree with this in general. On long pages with lots of code samples, I might use fancy ES6 functions in a couple of them just to throw that out there, but generally I try to avoid using most of them in typical articles.

Eric Shepherd
Senior Technical Writer
Mozilla
https://developer.mozilla.org/ <https://developer.mozilla.org/>
Blog: http://www.bitstampede.com/ <http://www.bitstampede.com/>
Twitter: http://twitter.com/sheppy <http://twitter.com/sheppy>