Editorial: disambiguate with statement's status

[ddbeck]

Currently, the spec sends mixed signals to programmers about the with statement; this PR attempts to clear up the ambiguity by adding text that explicitly discourages the use of the with statement in new ECMAScript code.

This is an attempt to solve a specific problem: developers and technical writers are unclear about the status of the with statement. See this StackOverflow question or this discussion in MDN Web Docs's browser-compat-data project to get a taste. This makes it difficult to document on MDN Web Docs and elsewhere.

By forbidding with in strict mode code and cutting it off from many contemporary language features, the specification seems to imply that programmers shouldn't use with, but this is less explicit than other disfavored parts of the language (e.g., the note for the getYear method or the introduction to Annex B). Because there's no single way that the spec indicates non-preferred features, developers and technical writers have to make do with close readings and interpretations.

Ideally, the specification could resolve the question definitively. This PR's fix to the problem is text that speaks directly to programmers, discouraging them from using the with statement. This is my attempt to put into words what I believe the existing text implies to programmers, but I'm open to making revisions which more accurately captures the posture toward with statement.

Thanks for considering this change!

[rolivo3]

The message must be very clear if this characteristic is going to be deprecated or not. One thing is for it to be discouraged and the other more traumatic for it to be deprecated.

The specification should have a more formal definition of "deprecated " and "discouraged".

Removing a feature is very painful on high impact. Also, if a characteristic that has been considered stable (for me if it has reached stage 3 or 4 of the process) is deprecated, the meaning of stable is lost, can this be clarified? What is stable and what is not?

[michaelficarra]

#2125 will be defining the term "legacy" for this purpose. However, applying the term "legacy" to a feature requires committee consensus, so this will have to be marked normative, not editorial.

[ljharb]

It seems like this might be better marked as "Legacy", once #2125 lands (which would require consensus)

[ljharb]

@michaelficarra i don't think it's normative just because it requires consensus.

[WebReflection]

There are no substitutes for the with statement, and the spec has Symbol.unscopables to deal with those cases too.

Discouraging with reasons looks like a good way forward, but "deprecating" it makes little sense.

I hope the obj.{ ... }; syntax, one day, will be back, otherwise we are all in Function('...') hands to bring back what with can do, as nothing else can.

[ljharb]

deprecation (in a context where basically nothing can be removed) is the same as discouragement.

[ddbeck]

Thanks for the comments here. I wasn't previously aware of #2125. "Legacy" seems like a great way to handle this sort of thing. When #2125 is merged, I'll be happy to update this PR to use the legacy attribute, though I'm not certain if my note should be retained or not.

applying the term "legacy" to a feature requires committee consensus

I'm new to contributing to the specification and the contributing docs don't seem to cover a case like this. What, if anything, should I do make it easier for the committee to consider this for consensus?

[michaelficarra]

@ddbeck The typical process would be to find a champion, which is a representative of a TC39 member organisation who will present your topic to committee during one of the regular meetings. If you update the language here to use the term "legacy", as defined in #2125, I will present this topic as a needs-consensus PR for you at the next meeting. The case for with is not as obvious as the already agreed-upon applications of "legacy", but I do personally think it merits the term.

[ddbeck]

@michaelficarra Excellent, thank you. I'd be delighted if you and the rest of the committee to take this up at the next meeting. I've updated the PR to use the term "legacy" and to set the legacy attribute for the clause (though this shouldn't really do anything until the other PR is merged). As soon as the other PR is merged, I'll rebase on top of that, too. Thank you again!

[ddbeck]

Since #2125 merged last week, I rebased my changes against the default branch and confirmed that this builds properly with the legacy attribute (since, as a first-time contributor, the GitHub workflows don't run).

I'll be happy to make any additional changes requested, as this proposal works its way through the process. Thanks again!

[michaelficarra]

@ddbeck This was presented to committee today (by @ljharb) and achieved consensus. 🎉

[bakkot]

We should put destructuring assignment inside of the xref element, so that it's not just a section number.

(Github isn't letting me comment directly on the PR for some reason.)

[michaelficarra]

@bakkot done