On Thu, May 20, 2010 at 8:19 PM, Jonas Sicking <jo...@sicking.cc> wrote:
> On Thu, May 20, 2010 at 11:55 AM, Shawn Wilsher <sdwi...@mozilla.com> > wrote: > > On 5/20/2010 11:30 AM, Andrei Popescu wrote: > >> > >> As someone new to this API, I thought the naming used in the current > >> draft is somewhat confusing. Consider the following interfaces: > >> > >> IndexedDatabase > >> IndexedDatabaseRequest, > >> IDBDatabaseRequest, > >> IDBDatabase, > >> IDBRequest > >> > >> Just by looking at this, it is pretty hard to understand what the > >> relationship between these interfaces really is and what role do they > >> play in the API. For instance, I thought that the IDBDatabaseRequest > >> is some type of Request when, in fact, it isn't a Request at all. It > >> also isn't immediately obvious what the difference between > >> IndexedDatabase and IDBDatabase really is, etc. > > > > It should be noted that we did not want to rock the boat too much with > our > > proposal, so we stuck with the existing names. I think the current spec > as > > written has the same issues. > > We kept the existing names specifically to avoid tying bikeshed naming > discussions to technical discussion about how these interfaces should > behave :) > Totally agree with both of you! But I think now is as good of a time as any to discuss these issues (since they apply to both specs). In this case, I actually don't think this is really bike shedding since we're all agreeing the current names are confusing, but I guess the line is fine. :-) > >> - I know we need to keep the "IDB" prefix in order to avoid collisions > >> with other APIs. I would therefore think we should keep the IDB prefix > >> and make sure all the interfaces start with it (right now they don't). > > > > I agree with this. We should probably file a bug about this. > > > >> - The "Request" suffix is now used to denote the asynchronous versions > >> of the API interfaces. These interfaces aren't actually Requests of > >> any kind, so I would like to suggest changing this suffix. In fact, if > >> the primary usage of this API is via its async version, we could even > >> drop this suffix altogether and just add "Sync" to the synchronous > >> versions? > > > > I agree that Request seems confusing and seems to be contrary to what > other > > specs use. We should try to follow what other specs do here. > > Agreed on both accounts. There unfortunately isn't much in the way of > precedence here. There are three other specs to look at here, which > specify API for both workers and main thread. > > * Web Workers spec > http://www.whatwg.org/specs/web-workers/current-work/ This spec > doesn't actually use different interfaces for workers and main thread. > * File API http://dev.w3.org/2006/webapi/FileAPI/ Specifies FileReader > and FileReaderSync. The two interfaces are separate and doesn't > inherit from a common base > * WebSQLDatabase http://dev.w3.org/html5/webdatabase/ Specifies > separate interfaces, like Database and DatabaseSync. The two > interfaces are separate and doesn't inherit from a common base. > > I think we should follow the same convention as File API and > WebSQLDatabase. There really isn't anything to be gained by having a > common base interface, it just makes the spec harder to read as > functionality is distributed between the base interface and the > sync/async interface. > > I additionally like the naming convention. The async interfaces is > probably the interface that people will use first. Additionally that > interface is available both to workers and to the main thread. So it > makes sense to give the async interface the simpler name. > Agreed on all counts. I would add that, if we did decide to keep base interfaces, we could always suffix them with Base (which I think makes it more clear they're base interfaces)...but it sounds like that might not be necessary. > >> - Some of the interfaces could have names that would more closely > >> reflect their roles in the API. For instance, IDBDatabase could be > >> renamed to IDBConnection, since in the spec it is described as "a > >> connection to the database". > > Not really sold on this. I've always hated the "connection" > abstraction. With our suggested API IDBDatabase really just holds > metadata information about the database, and doesn't need to represent > a connection at all. > Well, if we don't make these proposed changes, then I think it's pretty important to rename to connection since the current spec does distinguish between each connection. With your proposal, this is not currently true, but I think it's hard to say whether or not these concepts will creep back in in later versions. In addition, the entire spec is related to databases, so I think naming it a "connection" rather than a "database" helps distinguish it from the rest. That said, if IndexedDatabase* becomes IDBFactory* then there certainly is a lot less confusion already, and this change is less important. J