Subject: [Jmap] Call for objections - standardising on plural names everywhere

From: Bron Gondwana <[email-masked]>
Date: Mon, 27 Nov 2017 15:30:40 +1100

There was discussion in the room in Singapore about plural names
(Mailboxes) rather than singular (Mailbox)
e.g. we currently have:

getMailboxes
getMailboxUpdates
getMailboxList
getMailboxListUpdates
setMailboxes

Different words pluralise differently, and it makes it harder than it
needs to be to use automatic code generation for standard methods around
an object name.
The sense in the room was that nobody had a strong enough feeling to
push one way or the other (singular or plural), so I'm calling for
either agreement on plural, or an argument against it.  Silence will be
assumed to be agreement here.
https://github.com/jmapio/jmap/issues/164

The difficulty is finding names which aren't too verbose:  e.g. this is
very regular, but long!
getMailboxes
getUpdatesToMailboxes
getListOfMailboxes
getUpdatesToListOfMailboxes
setMailboxes

Bron.

--
  Bron Gondwana, CEO, FastMail Pty Ltd
  [email-masked]

---

From: Neil Jenkins <[email-masked]>
Date: Mon, 27 Nov 2017 15:41:02 +1100

Unless there are any objections, I'm going to standardise on plural
(because each of these methods deal with multiple instances of the
record type, not just one), and go with only a slight variation on the
current names (changes in *bold*):
getMailboxes
getMailbox*es*Updates
getMailbox*es*List
getMailbox*es*ListUpdates
setMailboxes

This is nicely consistent, and I think it's more readable than the other
alternative we tried (getUpdatesToListOfMailboxes etc.). If I don't get
any objections by next Monday, I'll do this.
Neil.

---

From: Neil Jhaveri <[email-masked]>
Date: Mon, 27 Nov 2017 12:22:09 -0700

Seems pretty reasonable to me.

> On Nov 26, 2017, at 9:41 PM, Neil Jenkins <[email-masked]> wrote:
> 
> Unless there are any objections, I'm going to standardise on plural (because each of these methods deal with multiple instances of the record type, not just one), and go with only a slight variation on the current names (changes in bold):
> 
> getMailboxes
> getMailboxesUpdates
> getMailboxesList
> getMailboxesListUpdates
> setMailboxes
> 
> This is nicely consistent, and I think it's more readable than the other alternative we tried (getUpdatesToListOfMailboxes etc.). If I don't get any objections by next Monday, I'll do this.
> 
> Neil.
> _______________________________________________
> Jmap mailing list
> [email-masked] <mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/jmap <https://www.ietf.org/mailman/listinfo/jmap>

---

From: Josef 'Jeff' Sipek <[email-masked]>
Date: Tue, 28 Nov 2017 08:58:38 -0500

> getMailbox*es*ListUpdates

Why not singular?  That is:

getMailbox
getMailboxUpdates
getMailboxList
getMailboxListUpdates
setMailbox

After all, the object is called Mailbox and not Mailboxes.  Yes, the methods
return an array of them, but using the singular term seems less awkward to
me since it avoids the double-plural in the get*Updates method names.

I don't care that much (IOW, plural is fine), but I thought I'd point out
another possible color for the bike shed :)

Jeff.

> [email-masked]
> https://www.ietf.org/mailman/listinfo/jmap

-- 
Fact: 26.7% of all statistics are generated randomly.

---

From: Stan Kalisch <[email-masked]>
Date: Tue, 28 Nov 2017 22:11:31 -0500

> On Nov 28, 2017, at 8:58 AM, Josef 'Jeff' Sipek <[email-masked]> wrote:
> 

I, too, find it less awkward without the double-plural, but sticking with only singular or only plural is still a vast improvement.

Thanks,
Stan

---

From: Neil Jenkins <[email-masked]>
Date: Wed, 29 Nov 2017 14:24:07 +1100

For completeness, copying to the list another suggestion from the GitHub
ticket[1]:
Mailbox.get
Mailbox.getUpdates
Mailbox.getList
Mailbox.getListUpdates
Mailbox.set

(You could also replace the "." with a slash, e.g. "Mailbox/get", which
I think I slightly prefer for readability.)
Not sure what response names you would use with this.

> I, too, find it less awkward without the double-plural, but
> sticking with> only singular or only plural is still a vast improvement.

I'm not overly concerned which one we pick. If there's a general
preference for singular over plural, I'm happy to go with that. The main
thing is it's consistent. The reason I picked plural is because the
methods all operate on multiple items at once, but I agree it is
slightly more awkward when combined with other plural words.
Neil.

Links:

  1. https://github.com/jmapio/jmap/issues/164