Re: [whatwg] [Fetch] API changes to make stream depletion clearer/easier

On 22/08/14 19:29, Brian Kardell wrote:
> On Fri, Aug 22, 2014 at 1:52 PM, Anne van Kesteren <annevk@annevk.nl> wrote:
>> On Fri, Aug 22, 2014 at 7:15 PM, Brian Kardell <bkardell@gmail.com> wrote:
>>> I still think that calling it bodyStream actually helps understanding
>>> all you need and it's short/portable...
>>>
>>> response.bodyStream.asJSON()
>>>
>>> seems to at least give the hint that it is a stream that is consumed
>>> without getting too crazy.
>>
>> Well 1),
>>
>>   response.json()
>>
>> is short too, much shorter in fact.
>>
> 
> It is, but there was concern that is was too short to be clear/might
> actually be confusing before it was further shortened.  Making it
> shorter doesn't help that objection - it doesn't make it clearer, does
> it?  I'm not saying "this is best" I'm offering a proposal that tries
> to strike the balance with this fact - that's all there is to my
> comment.

So my opinion is that there are two possible scenarios:

1) The API is consistent and friendly enough that, after an initial
period of learning how it works, developers will internalize the
semantics. In this case the short names are sufficient to describe the
functionality and should be preferred because they increase the signal /
noise ratio when reading and writing the code.

2) The API has semantics that are so liable to trip up developers that,
without reminder of the behaviour, they will constantly make mistakes.
In this case we should be working out how to design a less unfriendly
API, not bikeshedding which function naming scheme will make the problem
least bad.

I am slightly concerned that the amount of discussion around naming here
belies a belief that the underlying model is going to cause frustration
for developers. Is that the case?

Received on Saturday, 23 August 2014 18:12:01 UTC