[asterisk-app-dev] Event naming conventions

[Matthew Jordan]

On Mon, Oct 28, 2013 at 8:16 PM, Paul Belanger <paul.belanger at polybeacon.com
> wrote:

> On Mon, Oct 28, 2013 at 8:49 PM, Paul Belanger
> <paul.belanger at polybeacon.com> wrote:
> > On Tue, Oct 22, 2013 at 12:03 PM, Matthew Jordan <mjordan at digium.com>
> wrote:
> >>
> >> On Mon, Oct 21, 2013 at 3:23 PM, Michael L. Young <myoung at acsacc.com>
> wrote:
> >>>
> >>> ----- Original Message -----
> >>>
> >>> > From: "Daniel Jenkins" <dan.jenkins88 at gmail.com>
> >>> > To: "Asterisk Application Development discussion"
> >>> > <asterisk-app-dev at lists.digium.com>
> >>> > Sent: Monday, October 21, 2013 3:59:58 PM
> >>> > Subject: Re: [asterisk-app-dev] Event naming conventions
> >>> >
> >>> >
> >>> > > So, I guess the first question is do we want to keep the AMI / ARI
> >>> >
> >>> > > naming of events is _somewhat_ similar? AMI tends to be now,
> >>> >
> >>> > > DTMFBegin and ARI the past, PlaybackStarted.
> >>> >
> >>> > I'm sorry I even mentioned the AMI... I'd much rather keep it past
> >>> > tense...
> >>>
> >>> I too would lean more towards using the past tense.  It seems more
> natural
> >>> to see a message saying that "something has occurred".
> >>>
> >>
> >> Some thoughts here:
> >>
> >> When the event standardization for AMI occurred, we focused on two
> things:
> >>     (1) Making the events contain the same subsets of information
> >>     (2) Making the event types follow a "begin"/"end" nomenclature,
> without
> >> the need for a subtype field or further event field inspection
> >>
> >> Beyond that, there wasn't much thought given to whether or not event
> pairing
> >> should be "Started/Finished"; "Begin/End", "Created/Destroyed", etc.
> Maybe
> >> we should have been concerned about it, but our focus was more on the
> >> previous two points and not on whether or not Started is better than
> Begin.
> >>
> > To keep this thread going, I'm going to start work on a patch and I'll
> > be using past tense for the events. Here are some examples of the
> > syntax we use, what do people prefer:
> >
> > Started / Stopped
> > - StasisStarted / StasisStopped
> > - PlaybackStarted / PlaybackStopped
> >
> > Started / Ended
> > - StasisStarted / StasisEnded
> > - PlaybackStarted / PlaybackEnded
> >
> > Started / Finished
> > - StasisStarted / StasisFinished
> > - PlaybackStarted / PlaybackFinished
> >
> > Created / Destroyed
> > - BridgeCreated / BridgeDestroyed
> > - ChannelCreated / ChannelDestroyed
> >
> > Feedback welcome
> >
> Digging deeper into events, we also have the following:
>
> ChannelEnteredBridge / ChannelLeftBridge
>
> Seems like a mouthful, what about something along the lines of
>
> BridgeAdded / BridgeRemoved
> BridgeEntered / BridgedExited
>
> or event
>
> BridgeChannelAdded / BridgeChannelRemoved (mouthful)
>
> This is for /bridges/:id/addChannel / removeChannel function
>
> This will help keep all the bridge events in the same namespace:
>
> BridgeCreated
> BridgeDestroyed
> BridgeMerged
>
>
Two things:

(1) Sacrificing a few bytes is rarely worth it, even in the most strict of
real time systems. The amount of electrons perturbed by 7 characters is
worth the sacrifice it if it conveys meaning to the consumer of the API.

(2) The event conveys what happened: A channel entered a bridge, or a
channel left a bridge. Consider your alternatives:
* BridgeChannelAdded - somewhat acceptable, but now we've inverted the
order of the nouns in the event so it is somewhat less clear as to what
occurred. Is the object that was affected a bridge, a channel, or a
bridgechannel? (And yes, in Asterisk, a BridgeChannel is a thing. Just not
something an ARI consumer should ever be aware of.)
* BridgeAdded - what was added? A channel? Another bridge? (This is not so
absurd as you might think)
* BridgeEntered - again - what entered?

Again: ChannelEnteredBridge conveys exactly what just happened, a channel
entered a bridge. I don't even need to look at documentation to know what
that event implies.

How is that not better?

-- 
Matthew Jordan
Digium, Inc. | Engineering Manager
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at: http://digium.com & http://asterisk.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-app-dev/attachments/20131028/0ed4d55e/attachment-0001.html>