Re: [custom elements] Improving the name of document.register()

Thanks, Google folks, for considering a name to document.register. Though a small change, I think it will be a nice improvement to code clarity.

Since we're bikeshedding, let me add a few more notes in favor of defineElement for consideration:

1) In programming languages, you would normally say you "define" or "declare" a function, class structure, variable, etc. I don't know of any language where you "register" a function or class. Defining a custom element seems parallel to these cases. It is true that one "registers" a COM object. At first glance, that may seem like an analogous operation, but I don't think it really is. COM registration is usually done out of band by a separate tool, not by the program itself at runtime.

2) registerElement sounds kind of like it would take an instance of Element and register it for some purpose. defineElement sounds more like it is introducing a new kind of element, rather than registering a concrete instance of an element..

3) If we someday define a standardized declarative equivalent (note that I'm not necessarily saying we have to do so right now), defineElement has more natural analogs. For example, a <define> or <definition> element would convey the concept really well. But a <register> or <registration> or even <register-element> element would be a weird name.

4) The analogy to registerProtocolHandler is also not a great one, in my opinion. First, it has a different scope - it is on navigator and applies globally for the UI, rather than being on document and having scope limited to that document. Second, the true parallel to registerProtocolHandler would be registerElementDefinition. After all, it's not just called registerProtocol. That would be an odd name. But defineElement conveys the same idea as registerElementDefinition more concisely. The Web Components spec itself says "Element registration is a process of adding an element definition to a registry".

5) "Register with the parser" is not a good description of what document.register does, either. It has an effect regardless of whether elements are created with the parser. The best description is what the custom elements spec itself calls it

I feel that the preference for registerElement over defineElement may partly be inertia due to the old name being document.register. Think about it - is registerElement really the name you'd come up with, starting from a blank slate? I hope you will give more consideration to defineElement (which seems to be the most preferred candidate among the non-register-based names).

Thanks,
Maciej


On Dec 12, 2013, at 10:09 PM, Dominic Cooney <dominicc@google.com> wrote:

> 
> 
> 
> On Fri, Dec 13, 2013 at 2:29 AM, Brian Kardell <bkardell@gmail.com> wrote:
> 
> On Dec 11, 2013 11:48 PM, "Ryosuke Niwa" <rniwa@apple.com> wrote:
> >
> >
> > On Dec 11, 2013, at 6:46 PM, Dominic Cooney <dominicc@google.com> wrote:
> >
> ...
> >>> El 11/12/2013 21:10, "Edward O'Connor" <eoconnor@apple.com> escribió:
> >>>
> >>>> Hi,
> >>>>
> >>>> The name "register" is very generic and could mean practically anything.
> >>>> We need to adopt a name for document.register() that makes its purpose
> >>>> clear to authors looking to use custom elements or those reading someone
> >>>> else's code that makes use of custom elements.
> >>
> >> I think the method should be called registerElement, for these reasons:
> >>
> >> - It's more descriptive about the purpose of the method than just "register."
> >> - It's not too verbose; it doesn't have any redundant part.
> >> - It's nicely parallel to registerProtocolHandler.
> >
> >
> > I'd still refer declareElement (or defineElement) since registerElement sounds as if we're registering an instance of element with something.  Define and declare also match SGML/XML terminologies.
> >
> > - R. Niwa
> >
> 
> Define/declare seem a little confusing because we are in the imperative space where these have somewhat different connotations.  It really does seem to me that conceptually we are registering (connecting the definition) with the parser or something.  For whatever that comment is worth. 
> 
> While there's no consensus, I think this thread expresses a slightly stronger preference for registerElement than other proposals. I have filed this bug suggesting registerElement.
> 
> <https://www.w3.org/Bugs/Public/show_bug.cgi?id=24087>
> 
> Dominic