Re: [whatwg/encoding] Add Streams support (#72)

> That assumes that the user of the API just tries stuff and sees if DWIM magically happens. For an API user who works from understanding what they use, 1. is arguably more obfuscated than 3., because it's considerably less clear _why_ 1. works, so it's less likely that an API user who works from the point of view of understanding stuff would expect 1. to work.

Here's my mental model of what will happen:

1. Developer sees an example in documentation or a blog or stack exchange or somewhere and thinks "that's cool".
2. Sometime later, the developer finds they have a use for it, but they're fuzzy on the details. The developer who originally saw option 1. remembers that it was pretty simple, tries just calling the constructor, and finds it works how they expected. The developer who saw option 2. remembers that there was something a bit tricky about how to use it, and decides to do something else instead. The developer who saw option 3. remembers the name was kinda long with lots of capital letters and looks it up with a search engine.
3. Later again, the developer has another opportunity to use the feature. The developer who saw option 1. is now completely comfortable and does it without pausing. The developer who saw option 2. has completely given up and does something else instead. The developer who saw option 3. is now thoroughly convinced they can't remember the name of the API, and searches for it again. It will be a few more times before the fact that it is "TextDecoder" + "TransformStream" clicks in their brain and they don't need to waste time looking it up any more (see also: XMLHttpRequest).

I triage a lot of bugs. In my experience, 90% of the people who file bugs don't understand how stuff works. Those are the people I want to optimise for.

> Why? 1. has the most DWIM and, as a result, has the most opportunity for surprises.

This comes from my experience writing the tests in https://github.com/GoogleChromeLabs/text-encode-transform-prollyfill/blob/master/tests/non-interference.html. Just looking at the surface behaviour, it's not apparent that anything clever is going on under the covers at all. The developer doesn't need to know or care that we worked hard to make it happen.

I'm in favour of DWIM when there are no traps involved.

> 1. is obviously fewer characters to write than 3., but I think we shouldn't minimize the number of characters to write at the cost of API understandability.

What I meant from this is that we'd have to add two new sections, TextEncoderTransformStream and TextDecoderTransformStream, which would be very similar to the existing TextEncoder and TextDecoder sections. It would be harder to keep track of which section you were looking at, and implementers would have to play "spot the difference" to figure out which bits of functionality were different and which were common.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/encoding/issues/72#issuecomment-376407089