Modernization of (static) code examples

[teoli2003]

Hi all!

Our JS documentation dates back to ES3. We completely revamped it around 2014 (to ES5), and since then, we have kept up with new features in JS.

Keeping up means documenting the new features, but not necessarily updating all the previous docs to use these. Note that we don't want to use the fancy new features immediately everywhere as it takes a few years before they really become mainstream.

Nevertheless, a lot of our examples feel outdated, and beginners reading or using them will become used to outdated habits, which is not our goal. As an example, if you don't use for...of when possible your code doesn't go through many review process; the same if you use only var…

We at Open Web Docs have started to update these examples, feature by feature (e.g. using const and let instead of var), with the help of the whole MDN community.

I would like to launch the discussion here on the JS features we should use everywhere it is possible (and how to detect MDN pages that need to be updated). The idea is to create small-to-medium-size projects to fix them little by little.

What are the drawbacks? Given we will only use features that are widely supported, and not jump on the latest addition right away, there are very few negative points: mostly it will make the life of devs needing to support IE a bit more difficult, but with its obsolescence now officially acted, and most of these features already used in every blog and all over the web, it shouldn't bother us much.

I have a few entries to launch the discussion (I will update the list as the discussion progresses).

1. Use const and let instead of var [ES6/2015]
   This one is in progress: No more vars in JavaScript docs content#16614 and No more vars in Web/API content#16662 thanks to @wbamberg and numerous contributors (👏 )
2. Use for...of instead of the traditional for(;;) when going through array-like structures.
   We can find pages by looking for for loops calling the length property on the structure.
   In progress, too: Modernize JS in Web/API: Use for...of when possible content#18103 (Help welcome! 🧑‍🤝‍🧑 )
3. Use arrow functions where possible. [ES6/2015]
   We could look at the function keyword in samples, and check.<
   Note that we want to keep the parentheses around the parameters, even when there is only one.
4. Use implicit return (a.k.a. concise body) with arrow functions where possible. [ES6/2015]
   (e) => { return e.id } can be written (e) => e.id. (blog)
5. Use template literals where possible [ES6/2015]
   We can look for 'text' + ... + 'text' in samples to find most (but not all) cases.

Additions from the discussion here:

6. Use Object.hasOwn() instead of Object.hasOwnProperties() [ES2022]
   Supported by every browser; about 26 pages to update.
7. == -> === [pre-ES6]
   This is standard nowadays.
8. Replace forEach with for...of [ES6/2015]
   Use for...of if possible, then forEach(), and finally for(;;) if needed.
9. Fix function definitions that could use the method definition syntax [ES6/2015]
   Example of such change.
   In progress: Added shorter method definitions in objects for code examples content#18370
10. Replace a || b and a ? a : b by the nullish coalescing operator (??), and the optional chaining operator (.?) when pertinent. link to a concrete example [both ES2020]
11. Promise.finally() [ES2018]
12. Use async functions (await) (they already are ubiquitous on MDN for good reasons…) [ES2017]

Already in our guidelines, but not 100% enforced:

13. Use shortcuts for boolean tests — use x and !x, not x === true and x === false
    Already required by our guidelines, but we have about 32 pages with such erroneous tests.
14. Ban Hungarian notation for variable names.
15. Use literals — not constructors — for creating arrays (const x = ['bli', 'bla', 'blo'] not const x = new Array('bli', 'bla', 'blo'))
16. For object's members, use the dot notation (objName.objMember) rather than the bracket notation (objName['objMember']) whenever possible.
    ESLint rule to avoid it.

Rejected:

• Use the logical assignments (&&=, ||= [ES2021]
  Logical comparison in JS is a bit weird (as they don't return boolean values), so let's avoid this.

Proposed:

• Use classes instead of constructor functions [ES6/2015]
  ⚠️ No consensus for the moment.
• Use object destructuring and array destructuring, especially as parameters of arrow functions. [ES6/2015]
  ⚠️ No consensus for the moment.
• Use ??= as their meaning is obvious when used. [ES2021]
  ⚠️ No consensus for the moment. The idiom may be obvious and becoming quickly common.
• Use the numerical separators where possible: 1000000 = 1_000_000 as this helps legibility, is supported everywhere and easy to understand. [ES2021]
• Use optional catch binding: instead of catch(unused) {}, write catch {} [ES2019]

Note: Once we agree on a set of modernization, we must update our generic JS writing guidelines.

Principles. As the discussion progressed, we surfaced a few principles that we use to guide our decision. It will be useful to list them explicitly in the guidelines:

1. We want our code example and snippets to be easy to read, as we have the goal to teach good JS. A lot of modern JS features, naturally work towards this goal, but sometimes, they can make the code more difficult to understand. In these cases, we should avoid them. Non-exhaustive examples:
   • We always put parenthesis around single parameters of arrow functions: (event) => { handle(); } instead of event => { handle(); }
   • We accept /* */when the comment is intra-line and described a not-used parameter: (value, index /*, array */) = { …}. In such a case, the dev may copy the snippet and immediately knows that they can use the 3rd parameter if they have the need, without having a not-used variable. This would be an exception to the rule asking us to use \\ for comments.
2. JS features we want to use in our code example must be widely available:
   • All evergreen browsers should support them for some time in released browsers
   • Availability of the feature to transpilers so that people developing for older engines can set up a toolchain. (Our engine, mdn/yari, does this.)

There are probably other modern features we should start using. Any proposals?

cc/ @wbamberg, @sideshowbarker, @Elchi3, @Josh-Cena

[Josh-Cena]

Also

• Constructor functions to classes (this is tricky because constructor functions may be more illustrative of the prototype chain)
• == -> ===

[teoli2003]

I added == -> === (it was on my list but I forgot it…)

For constructor functions, do we have a way to detect them, so we can scope the work?

[sideshowbarker]

One question that comes to mind is, How much of this might we be able to check with existing linters or static-analysis tools?

I’m not familiar enough with the relevant JavaScript tools to know what the current capabilities are — but as for a prioritizing what things we should try to modernize first, I think it’d make sense to first do the things that we can check for with automated tools

[lionralfs]

Small update after fixing ~500 syntax errors to give you an idea of what we're dealing with:
I tried the ESLint rules arrow-parens and prefer-template seperately, here's the output:

• arrow-parens (Expected parentheses around arrow function argument): 1302 problems
• prefer-template (Unexpected string concatenation): 1022 problems

The --fix ESLint flag can do most (all?) of the work here, I'm willing to submit PRs in reasonable chunks, if wanted.

[Josh-Cena]

Arrow-parens can be fixed by Prettier so we don't have do that; prefer-template is a good one. I would be welcoming PRs.

[teoli2003]

Yes, PRs are welcome. Reasonable chunks are 100 files per PR (maybe 50 for the first one, so we can be sure all is fine)

[rubiesonthesky]

I can submit some prefer-template fixes that are under web-api. :)

[lionralfs]

The only ones I've missed should be the in the files my eslint setup didn't catch because I've ignored them. Feel free to fix those/check for newly introduced violations.

[Josh-Cena]

Note that we don't want to use the fancy new features immediately everywhere as it takes a few years before they really become mainstream.

This really depends on "what" kind of feature it is. Modern JavaScript tooling almost always assumes existence of transpilers/polyfills, so using bleeding-edge features is not a big deal—e.g. Object.hasOwn is definitely worth using, same as class fields.

[teoli2003]

Yes, you are right: the intended goal of the sentence was to prevent having a rule "It is in stage 3 or 4, so let's use it everywhere". I would prefer for us to define case by case.

Let's add Object.hasOwn to the list: despite being in ES2022, it is supported by every modern browser (we have about 26 pages to fix). It is also a new method, so is much easier to learn than a new language structure (like a new loop or destructuring arguments)

(To all: Feel free to argue if you disagree :-) )

[Josh-Cena]

Yes, I was mostly thinking about specced features. I just checked again and none of the stage 3 features seem ready/worthy for consumption (or I'm just not particularly excited about any of those), so stage 4 should be a good line.

[teoli2003]

Just a question (maybe I'm not yet awake). When should we use forEach or for...of (instead of a classical for())?

I think the advantage for...of will work with any iterable (not just Array, NodeList, and HTMLCollection) and goodies like continue or break are available (and more complex) in forEach. Should we impose one over the others, or just leave them to the taste of the author?

Is there a difference in performance?

[clshortfuse]

I say for...of instead. forEach() is exclusive to Arrays. We can't use it with generators.

For example, I was confused by MDN's base64 example example and was starting to write a modern version to donate it to MDN. See here. I found the use of generators would the code to be easy to read because for...of doesn't care if it's a String, Uint8Array or a generator, as long as there is an iterator.

As for airbnb eslint, I used it for years, but it's worth sunsetting now. IE11 is dead and we shouldn't worry about regenerator-runtime. Transcompilation to ES5 is becoming less and less necessary.

[7MinutesDead-Git]

Ok, so we should use for...of unless we need the array index (and we should use forEach if available) or do array method chaining. for(;;) is the last resort if we need the array index and forEach is not available on the structre.

For what it's worth, you can still access the index in a for...of loop (using syntax reminiscent of accessing indices in Python for loops).

for (const [index, item] of items.entries()) {
    //... 
} 

[Josh-Cena]

I find it interesting that we seem to be unanimously in favor of for...of 😄 I come from an environment favoring functional programming style and many I've worked with prefer forEach() since it seems less "imperative". Now that's definitely an illusion since forEach() is necessarily side-effect-ful so there's no FP-style purity in the end, but just sharing. I would definitely go with for...of by default.

for (const [index, item] of items.entries()) definitely works, but IMO it's much more roundabout than items.forEach.

[teoli2003]

Hehehe, I clearly come from an imperative background. 😄

It seems to me that we shouldn't make the use of for...of over .forEach() (or vice-versa) mandatory. It is a matter of coding style, and taste.

Even, when you need both the index and the value, it seems to me that for(;;) is perfectly fine (as well as for...of, .forEach(). (Note that my personal style is to use for (const [index, item] of items.entries()), but I'm not saying that this should be the rule).

So the idea would be to only avoid for(;;) if the index is not used (or in special cases).

[Josh-Cena]

Correct—I really don't have strong preferences for either, but since for (;;) -> for...of is a more trivial conversion that would be my go-to. For those needing indexes, let's go with "forEach() for one-liners", at least. We can see how many come up.

[teoli2003]

Should we also fix function definitions that could use the method definition syntax [ES6/2015]?

[teoli2003]

We don't have many cases of these, but I think we should explicitly ban – and fix the few occurrences – variables named using the Hungarian notation. I used it in C++ (during another life) and with static typing, it was a pain in the neck. Not something for dynamically typed language, IMO.

[teoli2003]

Replying to myself. This is already forbidden according to our JS Style Guidelines (not explicitly but as we require lowerCamelCase…) So I'm adding it to the list (checking other guidelines, so that we clean all of it!)

[teoli2003]

I propose to add:
Avoid String.concat(): Use template literals or the concatenation operators (+ or +=) instead.

[Josh-Cena]

That sounds more like a stylistic improvement than a "modernization" point? If we get a linter set up we have more freedom about what kind of styles to enforce.

[teoli2003]

True.

[teoli2003]

With @Josh-Cena, we found a place where the new Nullish coalescing operator was handy and clearly a new idiom. link to the concrete example

It replaces some occurrences of the two idioms that were previously used:

a || b
a ? a : b

by

a ?? b

|| always seemed a hack to me in JavaScript, though I use && all the time in the shell 🤷

A usual case is combined with the optional chaining operator:

a.?m ?? b

It is a much newer feature though: ES2020, but well-supported:

The optional chaining operator is also ES2020 and well-supported:

[teoli2003]

I don't think there is much work to be done, and I think it is already in use on MDN, but I think we should list (to explicitly allow it):

• Promise.finally() [ES2018]

[teoli2003]

@hamishwillee, I noticed you used object destructuring and I think we should add it to the list of modernization we would like to perform (even if it is less common):

Your example, combined with an implicit return in an arrow function.

const inventory = [
  {name: 'apples', quantity: 2},
  {name: 'bananas', quantity: 0},
  {name: 'fish', quantity: 1},
  {name: 'cherries', quantity: 5}
];
const result = inventory.findLast( ({ quantity }) => quantity < 2 );

[Josh-Cena]

FWIW—it may seem magical for new learners, but in production it has almost become the "industry standard". All the codebases I've worked on have enabled that rule (also part of Airbnb's ESLint config) and use destructuring assignment by default.

[teoli2003]

Note that using destructuring assignments (not in parameter position):

let array = ['one', 'two', 'three'];
let [ foo ]= array;
console.log(`Foo: ${foo}`); // logs 'one'

will have some impact as the idiom

let elt = parentDOM.getElementsByClassName("test")[0];

is used and will become:

let [ elt ] = parentDOM.getElementsByClassName("test");

How can we measure, or find, the usage of a modern JS feature?

[teoli2003]

Maybe @JeremiePat has some ideas/opinions here.

[Josh-Cena]

Speaking of to what extent we should use destructuring, I think this case is clearly beneficial, because we get rid of the duplicate prop identifier:

const prop = obj.prop;
// to
const { prop } = obj;

Key renaming is disputed, and almost certainly not worth migrating:

const val = obj.prop;
// to
const { prop: val } = obj;

Deep destructuring is also controversial, but I'm slightly pro-destructuring on this matter:

const subProp = obj.prop.subProp;
// to
const { prop: { subProp } } = obj;

Deep destructuring with renaming is pure chaos and should be avoided in examples.

Now what to do about function parameters is also a good point of discussion. I'm less pro-destructuring in certain cases. For example,

people.forEach(({ age }) => console.log(age));

Is arguably not any more readable than

people.forEach((person) => console.log(person.age));

Because it takes the age parameter out of its context and also loses the ability to give the first parameter a name, which is often self-documenting. (Of course this is a contrived example and the difference seems minor, but in production code it's more significant.)

So I hope to reach consensus on using destructuring for the first case, as well as destructuring assignment when multiple values are unpacked, but leave the rest to future discussions. (This includes the let [elt] = parentDOM.getElementsByClassName("test"); case since we are only unpacking one value and there's no duplication of identifiers, unlike objects)

[JeremiePat]

Hi 😁 !

I've been summon so, some quick thought about destructuring.

TL;DR: I'm quite on an agreement with @Josh-Cena

In the battlefield, I'm a strong supporter of destructuring assignment all the way (which is widely used among React users for example). That said, for documentation, I would advise to always think in term of legibility and understandability rather than modernity, compactness, efficiency or beautifulness.

For example :

destructuring + renaming + default assignment

const { prop: val = 'some default text' } = obj

function foo ({ uuid: id = null }) { /* ... */ }

Deep destructuring

const differentPersons = couple.filter(([
  { person: { name: nameA }} ,
  { person: { name: nameB }}
]) => nameA !== nameB)

This can be somewhat confusing when you are not a JS expert and documentation is not made for expert.

For the examples I'm given, on MDN, I would rather expect:

destructuring + renaming + default assignment

let { prop: val } = obj // Debatable but okay as there is only one syntax difficulty to handle.

if (val === undefined) {
  val =  'some default text'
}

function foo ({ uuid = null }) { /* ... */ } // Let's avoid useless renaming, but default assignment is good to show as it is common practice for function parameters.

Deep destructuring

const differentPersons = couple.filter(([a, b]) => a.person.name !== b.person.name) // way, way easier to understand !

[teoli2003]

I would like to suggest the logical assignments (&&=, ||= and ??=) as their meaning is obvious when used. [ES2021]

Support is great:

[JeremiePat]

Not a big fan of enforcing that syntax as it is less obvious than it looks. It is useful and it makes code more compact, but from experience many developers, for whom JavaScript is not their primary language, are easily confused by it (mostly because they are already confused by JS boolean operators as those operators do not return a boolean value). So I don't think we should be hard on it (but I would not discourage it either)

[Josh-Cena]

??= is very idiomatic. e.g. obj.someKey ??= []. I don't have strong opinions about others.

[teoli2003]

I forgot about the weirdness of logical comparison in JS… So yes, let's wait (at the minimum) for them.

For ??=, I'm unsure now.

[rubiesonthesky]

My two cents about ??= and it's friends. It's handy operator but it's also very confusing one, as it does multiple thing same time. I would be careful with adding that as it makes reading code more difficult for newcomers. I have not seen it really in any code examples over Internet that I have looked.

?? can be also hard to understand in the beginning but I think it fits the style of the examples.

Maybe these operators could be added in far future when other parts of the code examples are modernized first and ?? and ? operators are more common in examples. So maybe if this is done, it could be prioritized as last item and revisited before it's actually done, to see does it fit the wanted code style.

(I'm coming from outside of this project but I may be interested in taking part of the actual example updating later)

[teoli2003]

Yes, for the time being, we have rejected the logical assignments (||=, &&=, and likely ??=). Indeed we may revisit this in the future, as practice evolves.

[teoli2003]

I also would like to use the numerical separators where possible: 1000000 = 1_000_000 as this helps legibility, is supported everywhere and easy to understand. [ES2021]

[pmario]

As a user I do like "numerical separators", because they are easier to read. ... But

As a user that searches for reference docs about an eg: ES2018 syntax explanation, I wouldn't expect it. Let's say for whatever reason I'm locked to ES2018 syntax, this little "helper" would force me to switch to ES2021

As a user in general I would expect example code to be within 1 spec only. So in my case ES2018 only

just some thoughts.

[Josh-Cena]

@pmario Modern web dev almost always assumes transpilers/polyfills (especially if you have commitments to old runtimes), so we care much much more about approachability of examples than the actual spec version. Also I wouldn't expect, say, the let documentation to not contain anything higher than ES2015 simply because let itself is ES2015.

[teoli2003]

I think @pmario raised a very interesting point: many web devs have to target browsers that don't support modern features, and ofter very old browsers.

As pointed out, we cannot target a specific ES version inside a page: this is not practically doable (without even speaking about features that are modified/extended in newer ES versions).

The standard way of solving them is: Web developers write modern JavaScript, then transpile them.

In order to solve the problem raised by Mario, we must be sure that the modern features we want to use in our code samples are available in transpilers, in addition to their availability in engines.

I'm adding this to our Principles list in the original post.

[pmario]

I think @pmario raised a very interesting point: many web devs have to target browsers that don't support modern features, and ofter very old browsers.

I'm talking about visualisation terminals, that use an engine that is "locked" to a specific functionality. There may be thousands of installations, which are "air gapped" and can't be updated on the fly. They run the code as it is written. No transpiling needed or allowed, because the code that has been certified or audited has to be executed.

There are engineers, that need to maintain that software, with functions the specific engine supports. eg: ES2015. ... If I go to MDN and search for eg: promises, which have been introduced with ES2015 ... I would love to be able to copy paste a code example from MDN over to my system and run it.

But if one of the first examples, that explain promises 2015 uses .finally() ES2018, allSettled() ES2020 and again .any() ES2021 in the same example I'm stuck. ... It won't work with my software stack. .... Even if the code example is best practice. It won't work (for me)

So for me it would be nice if not all examples use the newest and shiniest syntax. If they can be copy / pasted into a system with specific capabilities, I think it would add extra value to the page.

I don't know if that wish is feasible, but at least I wanted, that you know about it.

BTW ... I also landed here because "JS weekly" mentioned it, in the "In Brief" section

The folks at MDN are discussing modernizing their code examples to modern JavaScript standards.

[teoli2003]

What about optional catch binding: instead of catch(unused) {} we can write catch {} [ES2019]

[Josh-Cena]

Yes, the three syntaxes above are definitely worth using.

[teoli2003]

As responses can move up and down in GitHub discussions, I'm just listing the three syntaxes here, so that the context of this comment is not lost:

• optional catch binding
• numerical separators
• logical assignment operators

[teoli2003]

Strangely, I think we have never stated this...

• Use // for comments. /*...*/ should be available for debugging.
  Note that the pattern fctName(param1, param2 /* unused */, param3) should be worked around (with something similar to fctName(param1, ...[ , param3]) – I need to test if it works).

A linter will find and mark them, but I think we should explicitly state it.

(This discussion will lead to some meta-docs describing what we discuss here and some actions to fix the actual content.

[JeremiePat]

I prefer clarity over modernity. In this case, for documentation such as MDN, using the /*...*/ comment makes better sens to clarify code sample intent.

[teoli2003]

This makes sense to me, you are right. I think we should explicitly allow /*...*/ to show dropped/not used params (and similar).

[teoli2003]

To capture this, I started a section about principles in the orignal post.

Principles. As the discussion progressed, we surfaced a few principles that we use to guide our decision. It will be useful to list them explicitly in the guidelines:

• We want our code example and snippets to be easy to read, as we have the goal to teach good JS. A lot of modern JS features, naturally work towards this goal, but sometimes, they can make the code more difficult to understand. In these cases, we should avoid them. Non-exhaustive examples: …

[tomayac]

Not sure if this came up: Lebab is the opposite of Babel and might help with some of the mechanical parts.

[teoli2003]

I didn't know about this tool and, indeed, this may help for some mechanical parts, but also for some extra points to consider for the modernization (consider = discuss before deciding to enforce or not).

Thanks!

[macgyver]

has anybody verified the claim that you will not get the job nowadays if you use var in your interview? I would personally not judge anybody harshly for that.

I have no objection to using modern syntax in the examples but I would (personally) want that claim to be backed up a bit before I did a ton of work to manually convert and test the current correctly-written examples using still-perfectly-valid javascript.

It seems more sensible to use modern syntax when adding or updating examples but accepting the old examples as they are. Updating pages for ancient apis to reflect modern coding styles does no good for the job applicants - would you also not get the job if you use getElementByClassName or getElementByTagName instead of querySelector?

[Josh-Cena]

I'm saying—for the vast, vast majority of the audience—they are better off by simply using const and following intuition (maybe acquired from another language) than getting tripped by, say, a var declaration escaping a block scope. For the purpose of proper education we do have the JS guide pages and reference pages that fully describe the nuances of hoisting or scoping, but—especially for web APIs—it's not the main focus of the page anyway, and we don't want to create extra obstacles for understanding or using the examples.

[macgyver]

I just parachuted in here from the js weekly newsletter, I haven't contributed much to these docs and I probably won't be the person to implement these changes so I'm in no position to speak, it just seemed to me that the time spent doing this work could be spent on better things. I still use var from time to time, it doesn't bother me if someone defines a variable w/ var within an if or try, intending to have access to it outside of that block, and I find it very useful when debugging old or transpiled code.

[Josh-Cena]

Ah, I didn't know it's on the JS weekly :) Sorry if I sound over-hostile.

And no, we do have enough person-hours to devote to these kinds of tasks. We have some very devoted volunteers that update ~30 pages per day. (And—to tell you the truth—this task quite matches their skill level.) It's not an urgent task and the team is not really sacrificing time and de-prioritizing other work.

[macgyver]

Right on, thanks for explaining.

[teoli2003]

Thanks for raising the point @macgyver. To update the JS, we will use three techniques:

1. As you said, we'll use modern JS on new examples/codes.
2. We'll change some problems "horizontally" (like fixing var -> const/let, …) by crowd-sourcing it. Plenty of young developers and students, or technical writers, help us. It is often a win-win situation: for some of them it is their first experience with git, and they learn a new skill; for us, we can move quickly on some of these repetitive tasks without abandoning others.
3. Finally we'll revise APIs "vertically", that is we update APIs that have evolved and the docs are a bit outdated.

(Thanks to @wbamberg who coined the two terms vertically and horizontally to describe these 2 approaches.)

This is not a project that will be done quickly, it will take several Quarters. Surely we will not stop all the other work (adding documentation for example), while doing it. Better an old-school example than no example at all.

[feketegy]

To be honest most of the things listed in the original post are unfounded, especially this statement:

As an example, if you don't use for...of when possible during a job interview, you don't get the job nowadays;

For example, arrow functions and "traditional" functions are two separate things with different behavior, or for..of and for (;;) are not mutually exclusive, or "use implicit returns with arrow functions wherever possible" is, again, more of a matter of preference than a "rule", some devs like the explicit return.

This whole post seems to be more like a style guide than anything, it's not like some of the old syntaxes are deprecated (or will be in the near future) and can't be used anymore, if that would be the case I could see a reason for this post.

[Josh-Cena]

Correct—most of them are stylistic. We are mostly striving to make our code examples mirror that written by actual companies today (especially the good ones).

@teoli2003 "Won't get the job" is certainly an overstatement (although it could be a sign of one not keeping up with the trend, which is dangerous in the ever-changing web world). I didn't realize it's there in the post!

[teoli2003]

I've rephrased it to speak about the review processes...

And yes, two syntaxes often have different nuances. That's why it isn't a find and replace project, but an improvement of the examples to use the most appropriate syntax.

[Vallek]

Use arrow functions where possible.

This doesn't sound like a good idea for beginner's documentation.

[Josh-Cena]

Most code examples are in the "references" section, where we would at least assume intermediate JS knowledge—or else it would be hard to present code at all. (Also, arrow functions are incredibly widely used today and I've rarely seen function expressions at all—not even sure if more people know function expressions exist than those who know arrow functions!)

Don't worry, we would still write the "guides" section the same way as before—we won't jump to using arrow functions before they are even introduced.

[teoli2003]

Yes, the Learning area will not have the same set of rules.

[Vallek]

I misunderstood then, thanks for answer!

[teoli2003]

I think we should update the pattern for...in combined .hasOwnProperty()/hasOwn:

For example:

for (prop in elementStyle) {
  if (elementStyle.hasOwnProperty(prop)) {
     out += "  " + prop + " = '" + elementStyle[prop] + "' > '" + computedStyle[prop] + "'\n";
  }
}

Would become the following, which is much easier to read and understand, even for a beginner:

for (const prop of elementStyle) {
      out += `  ${prop} = '${elementStyle[prop]}' > '${computedStyle[prop]}'\n`;
}

I think a significant amount of usage for .hasOwnProperty() on MDN is this pattern.

(This pattern has been uncovered by @maurer2 in this PR)

[Josh-Cena]

for...of and for...in are two things: for...of iterates, not enumerates the properties. The equivalent is ... of elementStyle.keys().

[teoli2003]

Oh yes, you are right! So:

for (const prop of elementStyle.keys()) {
      out += `  ${prop} = '${elementStyle[prop]}' > '${computedStyle[prop]}'\n`;
}

or even

for (const [index, prop] of elementStyle.entries()) {
      out += `  ${index} = '${prop}' > '${computedStyle[index]}'\n`;
}

And of course, in cases where the index is need only to access the value we shouldn't use keys() at all.

[Josh-Cena]

Ah, sorry, I messed up still: should be Object.keys(elementStyle)... If you can use elementStyle.keys() then elementStyle is already an array (or at least not a plain object).

[phawxby]

I'd like to vote for linting to require argument parentheses, sometimes having them and sometimes not is an unnecessary confusion that serves no purpose. They should be there all the time for consistency and let the build processes deal with them as necessary.

[teoli2003]

Do you mean for arrow functions? If so, I agree.

[Josh-Cena]

Yes, my personal style (and Prettier's default) would also add parentheses for arrow functions.

[teoli2003]

As a note, I'm enforcing it already in reviews. I hope we have Prettier hooked soon so that we can consistently enforce this.

Sometimes saving 2 characters is not worth the hassle. (And there are tools like minify to win it back further down the toolchain).

Edit: I added a note in the original post to make it clear.

[OnkarRuikar]

The ESLlint enforces the use of double quotes " by default. We should assert in our guide lines list what we want to use for HTML, CSS and JavaScript code.
This will reduce back and forth between contributors and reviewers. And code will look consistent across the website.

[Josh-Cena]

Both ESLint and Prettier have an option for this, so even if we adopted a formatter we have to bikeshed about how it should be configured 😄

[OnkarRuikar]

This is more stylistic than modernization so I suggest starting a new discussion—I anticipate some bikeshedding about this.

Hopefully these rules/decisions will make it to contribution guidelines, it would be good to mention this as well.
It's quicker to take decision on this here while the iron is hot. The new discussion will get only 2-3 views...

Note that the idea to use Prettier is to avoid the bikeshedding about this.

Exactly! We need to have it documented in contribution guidelines to stop future arguments.

---

Our current style guide points to Airbnb style. But Airbnb recommends single quotes. So I think we shouldn't leave this bike unparked. 🙃

[Josh-Cena]

Ugh, many big corps use single quotes—I guess that's an argument for productivity™. Nevertheless double quotes just "make more sense" to me, since you have to use them anyway in JSX, HTML, or languages making a difference between Char and Str.

[rubiesonthesky]

For me, it would make sense to use double quotes in examples and learning materials. And they are inline with html like JoshCena said.

This is another stylistic thing that I'd like to talk about which prettier will not probably solve. I think arrow function should use {} when it's not returning value. I.e. it should not "return" console.log for example. That is easy case to understand but sometimes it gets more complicated to understand, is the arrow function really returning some actual value. My guideline would be, that if you use return X inside brackets, then you could simplify it without brackrts. But if you would not have return, then it wouls make sense to uses brackets always. (And I know that you could do return console.log(value);) I think there is lint for "no confusing return" in Typescript eslint, so this is not new idea.

[Josh-Cena]

@rubiesonthesky Even with no-confusing-void-expression, I turn on the ignoreArrowShorthand option for my own config. I don't think it's confusing at all, and it saves two lines—sometimes even more. () => console.log("foo") has well-understood semantics.

[teoli2003]

We have completed this project. The Guidelines have been updated, and we have fixed most errors in mdn/content.

There is always more to be done, so feel free to submit PRs!

Thank you all for your help. It was an amazing journey! From this vivid discussion to the 50+ PRs and the code guideline revisions.

At some points, we'll want to fix code outside the mdn/content repository, but this will be for a separate project.

Thank you all. You rock! 🎉