Re: [NoInterfaceObject]

There seem to be two concrete examples here where Web API design guidelines over and above WebIDL formalism would be helpful.  See below

On Aug 29, 2011, at 1:57 PM, Andreas Gal wrote:

> 
> On Aug 29, 2011, at 1:49 PM, Robin Berjon wrote:
> 
>> On Aug 29, 2011, at 22:26 , Andreas Gal wrote:
>>> The current draft of the W3C Contacts API annotates every interface with [NoInterfaceObject].
>>> 
>>> http://dev.w3.org/2009/dap/contacts/
>>> 
>>> I tried to discuss this with the working group, but they feel that its important to not pollute the global name space.
>> 
>> You make it sound like the group just rejected your suggestion. As stated in http://lists.w3.org/Archives/Public/public-device-apis/2011Aug/0061.html:
>> 
>> "The idea behind using NoInterfaceObject is to avoid global namespace pollution unless there happens to be a good use case for exposing a given object (which there may well be, it might simply not have been suggested yet)."
>> 
>> I'm willing to be convinced otherwise, but this doesn't strike me as an absolutely terrible idea. In general though, I agree that it would be valuable to groups (and editors in general) to have guidance as to the tradeoffs involved in a given construct. In my experience, editors tend to just paste another API and start modifying it. They also tend not to have read the WebIDL specification (skimmed yes, read no). This tells me that some form of primer (possibly very short, not aimed at total beginners) might be called for.
> 
> I am all for tackling global name space pollution. Doing it on a per-spec basis is a terrible idea though. As I said, TC39 is tackling the problem with a bold step (eliminating the global name space).

And W3C could provide guidelines for when and how to introduce new global names and how to introduce object-based name-spacing to minimize the number of new global names introduced by emerging Web APIs.  This could be done now and doesn't have to wait for ES-Harmony modules.

> 
>> 
>>> I think this is wrong and breaks established DOM bindings patterns
>> 
>> I wouldn't assume that doing things differently from the DOM is necessarily bad. We don't have to care about Java.
> 
> Creating inconsistency is usually bad. Surprise rarely works in the favor of API users.

Particularly, one-off inconsistencies.  An discontinuity, as part of a migration plan leading to future consistency may be justified but that currently doesn't appear to be the situation.
...
>> 
>>> For general APIs we should disallow [NoInterfaceObject].
>> 
>> Disallowing seems harsh — that's why I prefer your previous suggestion of explaining in which cases to use it.
>> 
>>> The Contacts API for example defines this:
>>> 
>>> [NoInterfaceObject]
>>> interface ContactError {
>>> const unsigned short UNKNOWN_ERROR = 0;
>>> ...
>>> }
>>> This seems really counter-intuitive. Developers will want to use this by name (ContactError.UNKNOWN_ERROR).

It isn't even clear that there is agreement that Web APIs should be defining  new named Error objects.  See the thread starting with http://lists.w3.org/Archives/Public/public-webapps/2011JulSep/0133.html 
This is the other case where guidance that spanned all Web APIs would be highly desirable. 

>> 
>> Actually we should just replace this with a string, using numerical constants for error names is daft. But otherwise your point holds.
>> 
>>> Instead of arguing with each working group about their particular view of what good DOM bindings look like, we should add some guidance in WebIDL.
>> 
>> Discussing it with every group that does APIs would certainly require more patience and commitment than can be asked of anyone. I agree with the guidance idea (are you volunteering to draft something? :) but as state above I'm unsure that the WebIDL spec itself is the best place for this.
> 
> Its the best place I can think of, but I am very receptive to alternative suggestions :)

A interface definition language specification is a very different thing from a API design guideline document.  One tells  you want is expressible, the other tells you while forms of expression an API designer should choose. For example Microsoft .NET has a published set of guidelines (http://msdn.microsoft.com/en-us/library/ms229042.aspx ) providing guidance for designing the APIs of .NET frameworks and class libraries.

Ideally, there would be a W3C Web API Design Guidelines document that would be used in conjunction with the WebIDL spec.

Allen