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

I also really like defineElement. I am not sure that it is easy to
understand what it actually means to "register an element", where as
defining an element is pretty clear.

Kenneth

On Fri, Dec 13, 2013 at 9: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. 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
>
>



-- 
Kenneth Rohde Christiansen
Web Platform Architect, Intel Corporation.
Phone  +45 4294 9458 ﹆﹆﹆

Received on Friday, 13 December 2013 08:45:19 UTC