Better name for Commands.react

[jamesplease]

The current API is:

Events

trigger on, once, off listenTo, listenToOnce, stopListening

Commands

command react, reactOnce, stopReacting

Requests

request respond, respondOnce, stopResponding

@thejameskyle pointed out that 'react' is not a good name for Commands' handler. I agree. What's better? Hmmm...

[jamesplease]

//cc @jasonLaster this library is basically 100% ready to go aside from this issue.

[jasonLaster]

Cool!

On Friday, May 16, 2014, James Smith notifications@github.com wrote:

//cc @jasonLaster https://github.com/jasonLaster this library is basically 100% ready to go aside from this issue.

— Reply to this email directly or view it on GitHubhttps://github.com/jmeas/backbone.radio/issues/24#issuecomment-43295402 .

Jason Laster Software Engineer Etsy

[jasonLaster]

maybe replyTo

[jamesplease]

So...if you forget that RequestResponse was ever its name, and completely accept Requests as the new name, you might be receptive to this API:

// Commands
this.respond('some:command');
this.command('some:command');

// Requests
this.answer('some:request');
this.request('some:request');

You respond to commands and answer to requests.

Thoughts @jasonLaster @thejameskyle?

[jamiebuilds]

hmm I like that a little better, but I do think respond kinda implies its returning a value, less so than answer but still

[jamesplease]

Yeah good point @thejameskyle :(

[jasonLaster]

yea, while I like these, i'm still a fan of onCommand and onRequest because regardless of how cute it is, I'll still struggle to remember them.

[jamesplease]

I'll still struggle to remember them.

My problem with onCommand and onRequest is that it makes just one of the three methods memorable. You might remember it was pretty difficult coming up with the other method names with these method signatures.

By choosing to not use the name of the handler in the on method, you are correct that we introduce new terminology that is less easy to remember. But that new terminology is used in a consistent manner in all 3 methods, so I argue that it makes the collective API easier to digest.

// The trigger is just the name of the system. Super
// easy to remember.
command;
// The other 3 methods are all based off one word. You can't forget that
// there are 3 methods, so whatever word you choose would ideally
// apply to all 3. Respond, for instance, makes the entire API easy to
// remember.
respond;
respondOnce;
stopResponding;

// Otherwise...you only remember how to attach handlers...
command;
onCommand;
// What about the other methods?
onceCommand;
stopBeingCommanded;
// Using the same structure doesn't work. So you need to introduce
// a new concept entirely. This goes against your original goal of making
// things simple

If the API had 2 methods, then onCommand and onRequest would be the obvious choices. But, alas, there are 4 methods, so I'm just not sure if it works.

In both cases you will need to introduce a new concept. But in your example the division has one concept for trigger/on, and another concept for once/off. I find it much more natural to split it with trigger in one group and on/once/off in the other...just like Backbone.Events does.

[jamesplease]

I like actOn & actOnce for Commands, but stopActing makes no sense...the search continues.

[jamesplease]

How about 'handle'?

handle

handleOnce

stopHandling

configureAp: function() {
  this.localChannel.handle('show:region', this.showRegion);
  this.localChannel.respond('visibleView', this.region.currentView);
  this.localChannel.on('change:data', this.updateView);
},

onBeforeClose: function() {
  this.localChannel.stopHandling();
}

i like it

[jamesplease]

Also, it seems request-reply is a common name for the response of Requests. Maybe we should change it to reply?

this.reply('some:request');

this.replyOnce('some:request');

this.stopReplying();

For some reason I think it more clearly communicates the fact that there is a returned value moreso than 'respond,' even though they're practically synonyms.

[jamiebuilds]

request-reply :+1:

[jamesplease]

request-reply is a thing now, but the real problem, commands, is still unsolved :(

[paulfalgout]

How about command-comply? comply complyOnce stopComplying

or possibly command-obey obey obeyOnce stopObeying

request-reply and command-comply, with the alliteration and both ending in "ly" kind of have a ring to it.

And the definition of comply is: to act in accordance with a wish or command.

[jamiebuilds]

You had me at alliteration

[samccone]

:hear_no_evil: :goat:

[jamesplease]

Thanks for the suggestions, @paulfalgout! I've considered those verbs, myself, but I wasn't entirely convinced. I think it's because stopObeying and stopComplying seem a bit extreme...almost recalcitrant. stopReacting, stopHandling and the like sound a bit more toned down and neutral. Maybe this is a non-issue, though...

[jamesplease]

Resolved by #74 (manually merged)