The '?' and '!' syntax in algorithms is very poorly chosen

[bzbarsky]

There are several problems:

1. The choice to optimize for brevity at the expense of readability means the sigils are actually quite easy to miss. Especially '!', which is quite thin.
2. '!' has existing meanings as "not" that confuse people (e.g. when people see ! IsCallable(obj) in an algorithm they think that it means "obj is not callable".

Especially as people try to use these sigils in other specifications, with less-expert audiences than ecma262, this is causing real problems. I see the value in using a single algorithm-definition language in ecma262 and other specifications that define things in terms of EcmaScript objects, but if we want to do that we should seriously consider a more understandable syntax.

As a specific suggestion, '!' could be replaced with "unbox" or something along those lines. It would retain the clarity of extracting a value from the completion record, but make it even more clear that something nontrivial is going on, and for people who have never seen the syntax before make them stop and think about what "unbox" actually means instead of assuming that there's just a stray character in the spec draft, which is what they do now when they see the '?' and '!'.

[bterlson]

"unbox" doesn't say what "!" does which is both an unboxing and an assertion that the completion record is never an abrupt completion. The latter is really the most important part.

I'm open to changing (and agree with point 2 above) but I'd need to see a good alternative. We did discuss alternatives for some time so I don't anticipate this will be an easy task :)

[bzbarsky]

I'm not tied to "unbox", though it's common for "unbox" operations to assert that the unboxing is ok....

Is the existing discussion archived somewhere, in full or summary form? What alternatives were considered?

[bterlson]

#105 and #129 have some discussion. Not sure where the bulk of the syntax bike shedding happened, although much of it was IRC/elsewhere.

[claudepache]

I have to make some effort in order to not read "!" as "not"...

The best I'm currently thinking of are "unbox-or-throw" and "nothrow-unbox".

[ljharb]

✓? ᕕ( ᐛ )ᕗ

[allenwb]

! -> 👌
? -> 🤔

[bzbarsky]

I recomend using something people might actually have the fonts for.... ;)

[bterlson]

I am not against using Unicode for this in case folks are joking. It's not hard to set up your editor to make things easy to author and we have precedent (eg. « »).

I think ⏎ is reasonable for return-if-abrupt but I can't think of a good alternative for !.

[bzbarsky]

#105 and #129 have some discussion.

Thanks. None of the discussion there really considers non-single-char alternatives, looks like, or indeed any chars other than '!' and '?'...

There are suggestions in those issues to auto-linkify, though, which I think would have been a good idea no matter what: "read the algorithm conventions" is hard enough inside ecma262, given that they're not very prominent, but people are now trying to use this syntax in other specs, without ever really making it clear that they're using the ecma262 conventions ... and expecting people to guess that while in the middle of spec A (which is where they got dumped when they followed a link for "spec for X") they really need to go read some mildly-hidden preface matter from spec B to understand the notation is pretty annoying. ;)

[rossberg]

On 13 May 2016 at 23:49, Claude Pache [email protected] wrote:

I have to make some effort in order to not read "!" as "not"...

It's C's fault to make such a terrible and abusive choice for its "not"
operator... :)

[claudepache]

Here’s the result of my cogitation:

? → unbox check (to be applied from right to left);
! → unbox. The absence of check is an implicit assertion.

One could replace unbox and/or check, by some symbol; however we should make sure that it remains sufficiently clear for the occasional reader, especially in the few places where unboxing or returning-if-abrupt is not performed.

[michaelficarra]

If we're going to stick with symbolism, I'm partial to these square-based operators:

• ⊡ 'SQUARED DOT OPERATOR' (U+22A1)
• ⧆ 'SQUARED ASTERISK' (U+29C6)
• ⧄ 'SQUARED RISING DIAGONAL SLASH' (U+29C4)
• ⧇ 'SQUARED SMALL CIRCLE' (U+29C7)
• ⧈ 'SQUARED SQUARE' (U+29C8)
• ◳ 'WHITE SQUARE WITH UPPER RIGHT QUADRANT' (U+25F3)
• ▣ 'WHITE SQUARE CONTAINING BLACK SMALL SQUARE' (U+25A3)
• ☒ 'BALLOT BOX WITH X' (U+2612)
• ☑ 'BALLOT BOX WITH CHECK' (U+2611)

There's also a large selection of circle-based operators:

• ⊕ 'CIRCLED PLUS' (U+2295)
• ⊗ 'CIRCLED TIMES' (U+2297)
• ⊙ 'CIRCLED DOT OPERATOR' (U+2299)
• ⊛ 'CIRCLED ASTERISK OPERATOR' (U+229B)
• ⊜ 'CIRCLED EQUALS' (U+229C)
• ⎊ 'CIRCLED TRIANGLE DOWN' (U+238A)
• ⦹ 'CIRCLED PERPENDICULAR' (U+29B9)
• ⦼ 'CIRCLED ANTICLOCKWISE-ROTATED DIVISION SIGN' (U+29BC)
• ⦾ 'CIRCLED WHITE BULLET' (U+29BE)
• ⦿ 'CIRCLED BULLET' (U+29BF)
• ⧁ 'CIRCLED GREATER-THAN' (U+29C1)

[bterlson]

@michaelficarra I was also playing around with the square operators. Ballot box with x (with color: black which fixes the default red rendering on Windows at least) speaks to me as an unboxing operator, but I can't figure out a good way to differentiate an unbox return-if-abrupt from an unbox never abrupt. @michaelficarra what operators do you like for ?/! today?

I like unbox as a keyword too, as @claudepache suggests. check doesn't speak to me though. Also not sure about right-to-left evaluation order. What about unbox-normal and unbox-return or unbox-ria?

[annevk]

If you go as far as having Unbox and Check, then perhaps they should simply be abstract operations?

[domenic]

That would kind of break the idea that all abstract ops return completion records. They're probably better as syntactically "special" macros.

FWIW I like the current punctuators although the ! vs. negation confusion is sometimes annoying.

[leobalter]

I'm not super exited with unbox but IMHO it is better than unicode special characters as I don't know how they are read on any accessibility helper. I'm afraid they will end translated as "SQUARED DOT OPERATOR", in the middle of a sentence this is way more extra information than just "question mark", etc.

That would kind of break the idea that all abstract ops return completion records. They're probably better as syntactically "special" macros.

+1

[annevk]

That would kind of break the idea that all abstract ops return completion records.

That they don't all return such records explicitly is something I find very confusing. Also, e.g., IsCallable does not seem to get unboxed and is assumed to return a primitive by all its callers. So I don't think we have much consistency there one way or another.

[bterlson]

FWIW I like the current punctuators although the ! vs. negation confusion is sometimes annoying.

I'm in the same boat, but if people are confused, it should be fixed.

I'm afraid they will end translated as "SQUARED DOT OPERATOR", in the middle of a sentence this is way more extra information than just "question mark", etc

To be fair, screen readers don't read the current punctuators at all (and in general the spec is miserable to use with a screen reader). A lot of work needs to be done to make this better, and I doubt it matters what sigil we use as in any case we'll probably need ecmarkup to generate sensible aria-labels for pretty much everything :-P

That they don't all return such records explicitly is something I find very confusing.

My preferred understanding is that every abstract operation that describes runtime semantics returns a completion record. You can understand things like IsCallable in terms of the 6.2.2.2 semantics (hopefully temporary) that allow treating a completion record as a value when it makes sense to do so.

[bterlson]

FWIW I like the current punctuators although the ! vs. negation confusion is sometimes annoying.

I'm in the same boat, but if people are confused, it should be fixed.

I'm afraid they will end translated as "SQUARED DOT OPERATOR", in the middle of a sentence this is way more extra information than just "question mark", etc

To be fair, screen readers don't read the current punctuators at all (and in general the spec is miserable to use with a screen reader). A lot of work needs to be done to make this better, and I doubt it matters what sigil we use as in any case we'll probably need ecmarkup to generate sensible aria-labels for pretty much everything :-P

That they don't all return such records explicitly is something I find very confusing.

My preferred understanding is that every abstract operation that describes runtime semantics returns a completion record. You can understand things like IsCallable in terms of the 6.2.2.2 semantics (hopefully temporary) that allow treating a completion record as a value when it makes sense to do so.

[jmdyck]

@annevk:

If you go as far as having Unbox and Check, then perhaps they should simply be abstract operations?

Unbox could be an abstract operation, but Check has to be a shorthand (i.e., macro). If you try to write it as an abstract operation, then when it detects an abrupt completion and returns, it's just returning from Check, not from the caller.

[leobalter]

As I mentioned before, I don't like the idea of using Unbox, after thinking about it over the days and heavily based on the discussion on this issue, I believe the following might work as good replacements:

• ? becomes a check shorthand/macro
• ! becomes an assert shorthand/macro.

[claudepache]

? becomes a check shorthand/macro
! becomes an assert shorthand/macro.

That implies conventional implicit unboxing. In that case, we should make sure that the few places that use the unboxed completion records are marked with explicit non-unboxing, e.g.: « Let foo be the Completion Record returned by ... »

[domenic]

I'm in the same boat, but if people are confused, it should be fixed.

How many people are confused?

[bzbarsky]

Everyone I've talked to who has to look at the algorithms involved and wasn't involved in the initial discussions. That's 3 or 4 people so far.

[claudepache]

Given that boxing the returned value is usually implicit, it may be fine to have implicit unboxing:

• ? Foo() → return-if-abrupt Foo()
• ! Foo() → assert-not-abrupt Foo()
• Foo() → get-completion Foo()

[allenwb]

What's the current thinking about static semantics related abstract operations. They must never produce an abrupt completion and hence don't really need to use completion records and callers don't really need to unbox the result.

Is the intent to switch handle them switch them to also using completion records/unboxing but with the knowledge that they never produce abrupt completions?

[bterlson]

@allenwb My weak preference is to say that algorithm steps labeled "static semantics" don't return completion records, which means that static semantics don't need to uselessly use the !/?/whatever syntax. However I can understand not wanting to have two types of algorithms with different behavior. What do you think?

[rotu]

This is still tremendously confusing.

In the spec I see things like Perform ! CreateDataPropertyOrThrow. This seems contradictory. The ! means the operation is guaranteed never to return an abrupt completion but the name suggests that it can return a throw completion. Maybe it's a typo and this should be Perform ? CreateDataPropertyOrThrow instead?

In the streams spec, which inherits this ! syntax, I see ! ReadableStreamDefaultControllerError(controller, r). This suggests that the operation cannot throw; not even when called with a this value without the expected internal slots. (maybe it's missing a guard, like how numeric methods often start with Let x be ? ThisNumberValue(this value))

[bakkot]

It's not a typo. ! means that this particular call never throws. ! CreateDataPropertyOrThrow means that the property creation is guaranteed to succeed.

As to ! ReadableStreamDefaultControllerError, see whatwg/streams#1224 - that spec has not been updated following #2547, and therefore uses ! inconsistently, including when calling operations which never throw under any circumstances (rather than never throwing for the particular call in question).

[rotu]

It's not a typo. ! means that this particular call never throws. ! CreateDataPropertyOrThrow means that the property creation is guaranteed to succeed.

Okay, that matches my understanding. I have not inspected all cases of ! CreateDataPropertyOrThrow to show they can never result in an abrupt completion, but:

1. If an abrupt completion is impossible, ! CreateDataPropertyOrThrow seems a roundabout way of expressing the same thing as ! CreateDataProperty.
2. If a throw completion is possible, then it's not clear whether the intent is to rethrow, replace, or wrap the original exception.

As to ! ReadableStreamDefaultControllerError, see whatwg/streams#1224 - that spec has not been updated following #2547, and therefore uses ! inconsistently, including when calling operations which never throw under any circumstances (rather than never throwing for the particular call in question).

👍 Thank you!

[bakkot]

I have not inspected all cases of ! CreateDataPropertyOrThrow to show they can never result in an abrupt completion

Certainly if any of them can result in abrupt completion that would be an editorial error we'd need to correct. ! is an assertion that this does not happen and any violated assertion is an editorial error.

If an abrupt completion is impossible, ! CreateDataPropertyOrThrow seems a roundabout way of expressing the same thing as ! CreateDataProperty.

That doesn't express the same thing: CreateDataProperty returns false on failure rather than throwing, so merely calling Perform ! CreateDataProperty(...) does not express a guarantee that the property creation succeeds. For that we'd need to write Let _succeeded_ be ! CreateDataProperty(...); Assert: _succeeded_ is *true*. Which is very verbose to write all over the place.

[rotu]

If an abrupt completion is impossible, ! CreateDataPropertyOrThrow seems a roundabout way of expressing the same thing as ! CreateDataProperty.

That doesn't express the same thing: CreateDataProperty returns false on failure rather than throwing, so merely calling Perform ! CreateDataProperty(...) does not express a guarantee that the property creation succeeds. For that we'd need to write Let _succeeded_ be ! CreateDataProperty(...); Assert: _succeeded_ is *true*. Which is very verbose to write all over the place.

You're right. I think I must have been confused by the multiple flavors of failure (returning false versus an abrupt completion). For some reason, taking a perfectly ordinary boolean return value from CreateDataProperty and turning it into an assert-prohibited outcome ties my brain in knots!