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

On Dec 13, 2013 3:40 AM, "Maciej Stachowiak" <mjs@apple.com> wrote:
>
>
> 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.

My earlier comment/concern about confusion and overloaded terms was about
this exactly.  The language we are in here is js and we define a class
structure by subclassing, right?  The element is defined, its just that
that alone isn't enough - it has to be connected/plugged in to the larger
system by way of a pattern - primarily the parser, right?

>
> 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..

I don't disagree with that.  all proposals are partially misleading/not
quite crystal clear IMO.  I don't think registerElement is the height of
perfection either and perhaps reasonable people could disagree on which is
clearer.  At the end of the day I am inclined to not let perfect be the
enemy of good.

> 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.
>

Seems a similar problem here - you could be defining anything, plus HTML
already has a dfn...What about <element>?  That's already on the table
after a lot of discussion I thought - is it not what you meant?

> 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".

The scope part seems not huge to me... But by the same kind of argument,
you might just as easily make the case that what we are really lacking is a
registry member or something not entirely unlike jQuery's plugins
conceptually.

>
> 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
>
Can you elaborate there?  What effect?  Lifecycle stuff via new?

> 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?

For me, i think it still would be if i wound up with a document level
method as opposed to some other approach like a registry object.  But
again, i am of the opinion that none of these is perfect and to some extent
reasonable people can disagree.. I am largely not trying to convince anyone
that one way is right.  If it goes down as defineElement, the world still
wins IMO.

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
>
>