Prefer explicit algorithmic steps and constructs

[domenic]

For an example, see the before-and-after on Web Audio's OfflineAudioContext.prototype.startRendering:

before

after

Some points of note:

• Explicit use of flags, instead of saying things like "if it's called twice, throw an error."
• Explicit use of variables.
• Sequencing the steps of an operation, to make clear which of them are async.
• Explicitly firing events, instead of saying things like "The oncomplete handler will be called once the rendering has finished."

[annevk]

Yes! (Though for CSS specifications this might not always be desirable I believe. @dbaron and @tabatkins might have more to say.)

[ylafon]

Be careful of not imposing a mono-thread version of an algorithm that could otherwise be MT, as this might be harmful in the long run.

[annevk]

Yeah, we should probably also be cautious of any new synchronous APIs.

[tabatkins]

Nah, I mostly agree. Exactly how "algorithmic" is appropriate is up for debate, of course. (Compare Grid's current sizing algorithm which is explicit but readable, with the previous one which is barely-translated C++ code.)

[dbaron]

I think there are certainly contexts where advice to prefer algorithm steps could be interpreted in a way that produces bad results. The primary example I'm thinking of is the CSS syntax specification. Tab's early drafts of the spec were very algorithmic, and depended on the spec author manually maintaining invariants like brace-matching. It was in an algorithmic form that meant that a hard-to-detect spec error could break an invariant that we wanted to maintain perfectly (because we use these invariants to allow future extensions). I encouraged Tab to specify the invariants more directly, which simplified the specification, and made it much much harder for both spec authors and implementors who closely follow the specification to make those errors.

[dbaron]

Another area of concern is that there are cases where the spec author could choose multiple algorithms that produce equivalent results. However, later changes to the spec, or edge cases that the author hadn't thought of, might end up making it so that the different algorithms are no longer equivalent, and in order to be conformant, an implementation would effectively need to implement in the form that was in the spec. (I remember arguing with Tab about such an algorithm, which I suspect was in a selectors draft, although I've forgotten exactly what.) So it actually matters which algorithm is chosen, and it's absolutely not a purely editorial issue, because it may well end up being the way implementations have to implement it.

[chaals]

It seems generally useful to have well-written algorithmic constructs to show how things are meant to work. It also seems valuable to describe what is meant to happen in a non-algorithmic way, not least for people who just want know if the API does what they think when they are deciding whether and how to use the API,

[dbaron]

And one other point that just came up at today's TAG meeting: algorithms in specs should, like code, be understandable and reviewable. I've seen algorithms in specs that were clear and understandable, and I've seen some that where spaghetti code with weird side-effects across chapters.

[chaals]

+1 - and more generally, writing well makes a serious difference (whether it is algorithm, code, or prose).

[tabatkins]

The primary example I'm thinking of is the CSS syntax specification.

Syntax is still completely algorithmic. It just changed from being a state machine to a recursive-descent parser, which dramatically simplified tokenizing (you can reuse sub-algos when you can easily return to where you left off) and made the parser part easier as well. So this is just a matter of writing a good algorithm.

(I remember arguing with Tab about such an algorithm, which I suspect was in a selectors draft, although I've forgotten exactly what.)

It was about whether the selector match algorithm should be specified as using a selector left-to-right or right-to-left. Some selectors are easier to describe ltr, but browsers all implement them rtl.

[torgo]

We agree this is valuable and we need to include this. We will close #72 as a duplicate and @dbaron to write some text.