Re: IndexedDB, what were the issues? How do we stop it from happening again?

On Thursday, 7 February 2013 at 16:57, John Kemp wrote:

> On Feb 7, 2013, at 11:39 AM, Marcos Caceres wrote:
>  
> >  
> >  
> > On Thursday, 7 February 2013 at 15:43, John Kemp wrote:
> >  
> > > > What do you think?
> > >  
> > >  
> > > I think a TAG-like thing to do about that would be to publish a document  
> > > describing "W3C Best Practices for the Design of Javascript APIs", and  
> > > to take guidance from those places where it is considered good  
> > > Javascript is written (how about a collaboration with ECMA?)
> >  
> >  
> >  
> > I don't know if the TAG or ECMAScript knows best™.
>  
> OK, I agree with you, but what do you want the TAG to do about this issue?
Some members of the TAG, like Alex, have negative opinions about the IndexedDB API (or have ideas about how it could be done differently). Maybe they can explain what is bad in their eyes and what could have been done differently.  

For me, for example, I don't like that in order to get the API to do something, you have to wrap everything in a function. That is bad because it means I can't easily interact atomically with the API through a Javascript console. For me, that "sucks" as a developer.  
> Do you think "best practices" is a bad idea then?

Not all. Like I said, there is good best practices in some specs: they have to be applied directly to specs (like in WebIDL and DOM4). So, if anything, pain should be applied at the extension points of the platform (i.e., the stuff people are building on top of, which is HTML5, DOM4, WebIDL and maybe ECMAScript).

Here is helpful guidance from DOM4:
"Fire an event is a concept to make initializing and dispatching an event easier to write down. If the event needs its bubbles or cancelable attribute initialized, one could write "fire an event named submit with its cancelable attribute initialized to true"."   

Here is helpful guidance from WebIDL:
"Constants have in the past primarily been used to define named integer codes in the style of an enumeration. The Web platform is moving away from this design pattern in favor of the use of strings. Specification authors who wish to define constants are strongly advised to discuss this on the public-script-coord@w3.org mailing list before proceeding."

Stuff like the above is really helpful and it's right there where I need it as a spec editor (in the extension points that I am building on top of).

> How would *you* solve the issue you raised?
For IndexedDB, for instance, I would have made the request object more like XHR: where you set your event listeners (onreadystatechange, or whatever), then you call .send(). That unties the API from the javascript synchronous execution model (and lets me more easily interact with it through the JS console without needing to set breakpoints).  
> > The problem is that the guidance could be misapplied
>  
> So what would you do about that?

Having identified developers complaining about something, and having potentially identified a group that appears to potentially be making the same API mistakes (SysApps), I would email the TAG and ask TAG members to take a look at what a particular working group is doing (as a sanity check). I would hopefully get a range of opinions from the TAG, because there some clever people there (much more clever than me).   
  
> > (I'm thinking of all the APIs that tried to copy Geolocation, and failed spectacularly to understand what was actually good/bad about that API). Also, the design of an API should really be dictated by the use cases and ergonomic factors. Beyond simple stuff (e.g., the guidance given in WebIDL, like don't use numeric constants), there may not be much more that can be done. If anything, the TAG should be telling people to think really critically about API design and developer ergonomics
>  
>  
> Yes, but how?
If the TAG identifies a pattern, they could email the WG in question and say, "hey WG, we noticed you guys are doing X. Can you explain why you are doing that? We notices it resembles issues we have seen in the past, so we just wanted to make sure you are not repeating history. When another group tried to do something similar, Web devs said that it sucked.  
Love,  
The TAG"   
> > - road test APIs, get feedback, etc. and not just blindly copy patterns from each other. So maybe what is needed is some explanation of why things are the way they are in the platform (warts and all).  
> >  
> > But I don't know. Maybe all those people that said that IndexedDB sucks have an idea how it could have been done better? People like Yehuda, who is on the JQuery team, might have some ideas about assessing the usability (and non-suck aspect) of an API.  
>  
> Are you planning to ask those people what the TAG could do about this issue?

Yes. I would like to. But I want to know if other TAG members agree with me. I could be completely wrong (won't be the first time) and everything could be roses.    

> > > Other than that, I believe it is well within the rights of individual  
> > > W3C WGs to publish APIs that meet the needs of the WG members.
> >  
> >  
> >  
> > This seems counter to the W3C's primary goal:
> >  
> > "The social value of the Web is that it enables human communication, commerce, and opportunities to share knowledge. One of W3C's primary goals is to make these benefits available to all people, whatever their hardware, software, network infrastructure, native language, culture, geographical location, or physical or mental ability." - http://www.w3.org/Consortium/mission.html
>  
> That's certainly a W3C organizational goal.
You would hope that is why people join the W3C.   

> >  
> > If members were only serving their own interests, many of the things above would not be addressed.
>  
> The W3C seeks also to address the needs of its members. Often it is not clear when an API is begun whether it will "enable[s] human communication, commerce, and opportunities to share knowledge". That's why members decide to create an XG or WG and write a spec. They are often at the beginning phase of knowing whether their products based around the spec. will succeed.
>  
> > To illustrate, the above is at the core of why so many people are up in arms about DRM. But please lets not have a DRM discussion here.  
>  
> DRM perfectly illustrates the potential tension between the needs of some W3C members and the W3C goal you mention above.
Exactly. I think it's really healthy because it shows that the W3C's goal is not just rhetoric, but something people care deeply about and are willing to fight for.   
>  
> >  
> > > Opinions  
> > > of taste run secondary to those needs, but I'm sure that should good  
> > > advice be given, WGs would at least listen to it.
> >  
> >  
> >  
> > Um, the needs are generally: "we want to make an API to allow X that people will want to use".
>  
> Then why don't they?
That's exactly what we are trying to find out.   
> >  
> > If you then say, "oh, we don't care if the developers don't like it", then you probably are going to have some pretty serious problems (specially when there are lots of platforms competing for developer mindshare).  
> >  
> > The *happy* developer should be at the forefront of every API decision.
>  
> Who is the happy developer though? Not all APIs are designed for the same developers.
APIs that are designed to go into browsers are designed for the same developers.   
> > We make APIs for people to use, and *secondarily* to solve some problem. Without the developer using it (or if the developer can't use it), then you can't actually solve the problem the API was designed to address.  
>  
>  
> I agree that APIs have developers as customers. But they are designed to solve particular problems, or to perform particular tasks. Those tasks won't make *all* developers "happy" to use an API just because.
>  

If we really want the platform to continue to be relevant, having interoperable implementations is simply not enough. Sure, we can't make everyone happy - but we should make the majority of devs happy. Or if one makes devs unhappy, it is important to figure out how not to do it again.

Received on Thursday, 7 February 2013 17:38:57 UTC