Re: [contacts] Extending the Contacts.create() method

On 21.12.2009, at 19.32, ext richard.tibbett@orange-ftgroup.com wrote:

> Hi,
>
> Just documenting some thoughts on improving the Contacts.create(...)
> method [1] to allow for additional contact attributes to be  
> specified at
> object creation.
>
> The method could be overloaded as follows:
>
> interface Contacts {
>    Contact   create (in DOMString name);
>    Contact   create (in ContactProperties options);
>    // ... Other methods
> };
>
> Or it could be extended with optional additional contact attributes as
> follows:
>
> interface Contacts {
>    Contact   create (in DOMString name, in optional ContactProperties
> options);
>    // ... other methods
> };
>
> Any feedback on the best approach, or whether the current simple
> create(...) method [1] is sufficient is welcome :-)


I also support molding the create() method a bit. However, I'd like to  
hear some reasoning why to select one alternative over another. Here's  
my pondering:

1) The first alternative is familiar to some web developers (some  
popular JavaScript libraries use it) and it is also a bit more dense  
for the simplest use case. Implementation relies on type checking  
which may be a downside (String and Object data types are easy to  
distinguish whereas Array vs. Object could potentially be more  
problematic as typeof [] says object instead of array since arrays  
inherit from objects -- an implementation detail perhaps that can be  
worked around):

interface Contacts {
    Contact create (in DOMString name);
    Contact create (in ContactProperties options);
    // ... Other methods
};

2) The second alternative is more consistent with the other W3C APIs  
such as Geolocation and HMTL5 associated APIs but it is a bit more  
verbose as well. Uses method overloading:

interface Contacts {
    Contact create (in DOMString name, in optional ContactProperties
options);
    // ... other methods
};

3) The third option would be to always pass a single object literal  
only. This style is also used by some popular libraries and is thus  
known to developers, is extensible and consistent within itself. It is  
also self-documenting (the property names are always visible in the  
object literal). In addition, regarding this particular API it is also  
consistent with the find() which also takes ContactProperties as the  
first argument. Does not require method overloading, which can be  
considered a good thing. I think the simplest use case (create a  
contact object and define only its name) is not too common and thus  
some extra typing required in that case is not a problem. Thus I'd  
vote for #3:

interface Contacts {
    Contact create (in ContactProperties options);
};

Example usage:

create({ name: 'John Doe' });
create({ name: 'John Doe', nicknames: ['Johnny'] });

-Anssi

Received on Friday, 8 January 2010 17:53:19 UTC