(In reply to comment #0)
> Sorry to drudge up bug #627397 again, but the *Owner interfaces are becoming
> more and more awkwardly-named as we add new ones.
> 
> Mostly because it sounds like the Individual or Persona "controls" the subject
> in question (which is obviously multiply-awkward in the case of "GenderOwner").
> And that's completely backwards for the proposed Organisation interface (which
> would be named "OrganisationOwner", when the Individual/Persona is actually a
> *member of* the organization).

That is a problem, and something we need to fix. How about calling it “OrganisationMember”?

> I propose we just chop off "Owner" from these "has-a" interfaces. It does mean
> we're stuck with the slightly-awkward "individual is Avatar",
> "FOLKS_IS_ORGANIZATION (persona)", "birthday = FOLKS_BIRTHDAY (individual)",
> etc., but I think object-oriented developers would adjust quickly.

I don't think that's a decent solution, for all the reasons outlined in previous bug reports. I'd prefer having a slightly non-standard name for the Organisation interface to renaming everything else again when their names are generally OK already.

That said, I'm more than open to someone else coming up with a brilliant new naming scheme which solves all our problems…please?

(In reply to comment #1)

> That said, I'm more than open to someone else coming up with a brilliant new
> naming scheme which solves all our problems…please?

Danielle helped me brainstorm a little more - here were the best ones:

adjectives for has-a (where there's a word), *Publisher for has-a (where there's no real adjective), *Member for is-a

Named, Gendered, Addressable, OrganisationMember, BirthdayPublisher, PostalAddressPublisher, Favouritable, NotesPublisher

The main problem here is that NotesPublisher is a little non-sensical (since these are notes the user added to one of their contacts, not notes a contact told you about themselves). Also, 3 distinct rules is kind of confusing (especially since two of them are for essentially the same type of interface).

===============

Another option is *Impl (short of "Implementor" or "Implementation"), which gives us:

AvatarImpl, NameImpl, GenderImpl, EmailAddressImpl, OrganisationImpl, BirthdayImpl, PostalAddressImpl, FavouriteImpl, NotesImpl, ImAddressImpl.

And C macros like:

FOLKS_IS_NAME_IMPL(persona)
bar = FOLKS_ORGANISATION_IMPL (foo);

I think it's generally nice aside from the awkward abbreviation. And it would be slightly confusing if we eventually did create a real Avatar class that AvatarImpl would use for its members (though it wouldn't be the end of the world).

Ideally, this would be *Iface or *Interface instead of *Impl, but Vala will generate structures with those names behind the scenes, causing confusion for C developers.

And, one last variant would be IPresence, IAvatar, etc., but that's a little tacky.

(In reply to comment #2)
> (In reply to comment #1)
> 
> > That said, I'm more than open to someone else coming up with a brilliant new
> > naming scheme which solves all our problems…please?
> 
> Danielle helped me brainstorm a little more - here were the best ones:
> 
> adjectives for has-a (where there's a word), *Publisher for has-a (where
> there's no real adjective), *Member for is-a
> 
> Named, Gendered, Addressable, OrganisationMember, BirthdayPublisher,
> PostalAddressPublisher, Favouritable, NotesPublisher
> 
> The main problem here is that NotesPublisher is a little non-sensical (since
> these are notes the user added to one of their contacts, not notes a contact
> told you about themselves). Also, 3 distinct rules is kind of confusing
> (especially since two of them are for essentially the same type of interface).

I like it. What's the difference between Addressable and PostalAddressPublisher?

How about Annotated instead of NotesPublisher (or some other description which uses a synonym for “notes”)?

> ===============
> 
> Another option is *Impl (short of "Implementor" or "Implementation"), which
> gives us:
> 
> AvatarImpl, NameImpl, GenderImpl, EmailAddressImpl, OrganisationImpl,
> BirthdayImpl, PostalAddressImpl, FavouriteImpl, NotesImpl, ImAddressImpl.
> 
> And C macros like:
> 
> FOLKS_IS_NAME_IMPL(persona)
> bar = FOLKS_ORGANISATION_IMPL (foo);
> 
> I think it's generally nice aside from the awkward abbreviation. And it would
> be slightly confusing if we eventually did create a real Avatar class that
> AvatarImpl would use for its members (though it wouldn't be the end of the
> world).
> 
> Ideally, this would be *Iface or *Interface instead of *Impl, but Vala will
> generate structures with those names behind the scenes, causing confusion for C
> developers.

This sort of scheme is nice and regular, but wouldn't it generate weirdly-named C structures like “AvatarImplIface”?

> And, one last variant would be IPresence, IAvatar, etc., but that's a little
> tacky.

Bleh.

(In reply to comment #3)

> > Named, Gendered, Addressable, OrganisationMember, BirthdayPublisher,
> > PostalAddressPublisher, Favouritable, NotesPublisher
> > 
> > The main problem here is that NotesPublisher is a little non-sensical (since
> > these are notes the user added to one of their contacts, not notes a contact
> > told you about themselves). Also, 3 distinct rules is kind of confusing
> > (especially since two of them are for essentially the same type of interface).
> 
> I like it. What's the difference between Addressable and
> PostalAddressPublisher?

Same as with Addressable and PostalAddressOwner -- Addressables are actionable by Folks itself; PostalAddressPublishers fields aren't. But distinctions like this are why I'm much more inclined to a <Noun>Keyword naming scheme like below.

> How about Annotated instead of NotesPublisher (or some other description which
> uses a synonym for “notes”)?

I'd be fine with that (though it's not as nice as <Noun>Keyword).

> > ===============
> > 
> > Another option is *Impl (short of "Implementor" or "Implementation"), which
> > gives us:
> > 
> > AvatarImpl, NameImpl, GenderImpl, EmailAddressImpl, OrganisationImpl,
> > BirthdayImpl, PostalAddressImpl, FavouriteImpl, NotesImpl, ImAddressImpl.
> > 
> > And C macros like:
> > 
> > FOLKS_IS_NAME_IMPL(persona)
> > bar = FOLKS_ORGANISATION_IMPL (foo);
> > 
> > I think it's generally nice aside from the awkward abbreviation. And it would
> > be slightly confusing if we eventually did create a real Avatar class that
> > AvatarImpl would use for its members (though it wouldn't be the end of the
> > world).
> > 
> > Ideally, this would be *Iface or *Interface instead of *Impl, but Vala will
> > generate structures with those names behind the scenes, causing confusion for C
> > developers.
> 
> This sort of scheme is nice and regular, but wouldn't it generate weirdly-named
> C structures like “AvatarImplIface”?

I think it would be very rare that a developer would ever deal with that directly. GLib recently added some G_DEFINE_... macros for interfaces which make it rare that you'd ever need to write that structure name out (and even if they didn't, it's not something that would appear in much code).

(In reply to comment #4)
> I think it would be very rare that a developer would ever deal with that
> directly. GLib recently added some G_DEFINE_... macros for interfaces which
> make it rare that you'd ever need to write that structure name out (and even if
> they didn't, it's not something that would appear in much code).

Very true. Perhaps you should make an executive decision between the two ideas? I don't mind either way.

(In reply to comment #5)

> Very true. Perhaps you should make an executive decision between the two ideas?
> I don't mind either way.

OK, then - let's name our interfaces <Noun>Impl and be done with it.

(In reply to comment #6)
> (In reply to comment #5)
> 
> > Very true. Perhaps you should make an executive decision between the two ideas?
> > I don't mind either way.
> 
> OK, then - let's name our interfaces <Noun>Impl and be done with it.

Slight improvement (?): <Noun>Details.

The real commonality for all of these interfaces is that they each represent one detail or a collection of the same type of details for an Individual or Persona implementation. Slapping "Impl" or "Iface" doesn't really convey that (in addition to being awkward).

AvatarDetails, NameDetails, PostalAddressDetails, OrganizationDetails, GenderDetails, PresenceDetails, BirthdayDetails.

So I think the only downside with this approach is:

persona is AvatarDetails // FOLKS_IS_AVATAR_DETAILS (persona)

But it manages to get us a consistent, simple naming scheme that doesn't conflict with existing structure names (as with "Iface"), casting looks good in C (FOLKS_AVATAR_DETAILS (persona)), and it doesn't leave me wishing for a better scheme.

This seems better than the other consistent suffices proposed. The downside in Vala you mention is not ideal, but it's fine, I'll stop complaining about naming in a library I don't personally use. :p

Created attachment 183111 [details] [review]
Rename the *able and *Owner interfaces to *Details

Patches from branch:

http://git.collabora.co.uk/?p=user/treitter/folks.git;a=shortlog;h=refs/heads/bgo642513-interface-names

Review of attachment 183111 [details] [review]:

Looks good to me.

(In reply to comment #10)
> Review of attachment 183111 [details] [review]:
> 
> Looks good to me.

Thanks for the review. Merged:

commit 495af30846165cbed89545bf844af9266b7797d0
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 17:11:48 2011 -0800

    Rename Urlable -> UrlDetails
    
    Fixes bgo#642513 - Folks "Owner" interfaces are awkwardly-named

commit 82685d87b6def34fd92401d8e9e824f0f4e366e0
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 17:04:55 2011 -0800

    Rename RoleOwner -> RoleDetails
    
    Helps bgo#642513 - Folks "Owner" interfaces are awkwardly-named

commit 095ca9bccd5429ff54d6dcfe43baf90c49b05885
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 16:59:25 2011 -0800

    Rename PresenceOwner -> PresenceDetails
    
    Helps bgo#642513 - Folks "Owner" interfaces are awkwardly-named

commit 27935c24c2b5f62446094c40b6459b5537c0d71f
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 16:46:11 2011 -0800

    Rename PostalAddressOwner -> PostalAddressDetails
    
    Helps bgo#642513 - Folks "Owner" interfaces are awkwardly-named

commit 3c972a9ee7e701e1cd6ce0b23f491b6d9f6ee352
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 16:40:50 2011 -0800

    Rename Phoneable -> PhoneDetails
    
    Helps bgo#642513 - Folks "Owner" interfaces are awkwardly-named

commit e6c6b6aaa90ef15fdc42d317b5089cf9a833d7bc
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 16:34:44 2011 -0800

    Rename NoteOwner -> NoteDetails
    
    Helps bgo#642513 - Folks "Owner" interfaces are awkwardly-named
commit bb99bfe38e36de6a01cbdf351b1f215f99c90bfa
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 16:30:05 2011 -0800

    Rename NameOwner -> NameDetails
    
    Helps bgo#642513 - Folks "Owner" interfaces are awkwardly-named

commit 9086a10c502e55ea7e57d9ae795333b81a701f0b
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 16:23:55 2011 -0800

    Rename IMable -> ImDetails
    
    Helps bgo#642513 - Folks "Owner" interfaces are awkwardly-named

commit b2a60c1f8bc8d032ce99a4bd1e7ec53106da9c63
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 15:11:27 2011 -0800

    Rename Groupable -> GroupDetails
    
    Helps bgo#642513 - Folks "Owner" interfaces are awkwardly-named

commit 4cbdbf9b30095f5e5de3378e23f80c94810e829e
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 15:14:26 2011 -0800

    Rename GenderOwner -> GenderDetails
    
    Helps bgo#642513 - Folks "Owner" interfaces are awkwardly-named

commit b181a6587e3be54f0a6cef9109534c9801659c02
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 14:53:06 2011 -0800

    Rename Favouritable -> FavouriteDetails
    
    Helps bgo#642513 - Folks "Owner" interfaces are awkwardly-named

commit 26ade1fe73a0c18d8ad6c60e1b31b4c6547af79d
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 11:59:25 2011 -0800

    Rename Emailable -> EmailDetails
    
    Helps bgo#642513 - Folks "Owner" interfaces are awkwardly-named

commit fbc1d396fd6f62f9c70d3e2376f58025e9e21138
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 15:52:50 2011 -0800

    Rename BirthdayOwner -> BirthdayDetails
    
    Helps bgo#642513 - Folks "Owner" interfaces are awkwardly-named

commit e6782e4fad7e3d9399ba5a38555a4fb9da8b0017
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 15:32:27 2011 -0800

    Rename AvatarOwner -> AvatarDetails
    
    Helps bgo#642513 - Folks "Owner" interfaces are awkwardly-named

commit b6a398ccf36e54ec9d45b9478538bbeff6d74ea8
Author: Travis Reitter <travis.reitter@collabora.co.uk>
Date:   Thu Mar 10 11:55:07 2011 -0800

    Rename Aliasable -> AliasDetails
    
    Helps bgo#642513 - Folks "Owner" interfaces are awkwardly-named