On 09/13/2012 09:28 AM, Ted Ross wrote:
On 09/13/2012 09:00 AM, Justin Ross wrote:
Hi, everyone.

In my opinion, the engine api could benefit from being less terse and using systematic naming. The naming is already systematic in some respects, but it has idiosyncracies that I found consternating when I was trying to figure out what was going on.

I've attached my proposal for a "naming protocol". Of course, naming things is a little like poetry, with a lot of information to carry in very little space. I appreciate that there are big tradeoffs here. However, I think the engine api as it stands makes the tradeoff much too firmly in the direction of brevity, and away from clarity.

Why take a systematic approach such as this? Two reasons are foremost for me:

1. The api names should answer questions. What type does this function
     operate on?  Is it an accessor or an action?  The protocol
establishes a cross-api pattern that can often, if not always, answer
     such questions.

  2. The api names should reduce the programmer's memory burden. Since
     the api names share a grammar, it's relatively easier to remember
them. Once you know the protocol, "I want to settle the delivery" is
     seamlessly translated into "pn_delivery_settle."

I've included java names here for comparison. They helped me to think about what names were sensible, and I hope perhaps this discussion of the c api can also be extended to the java one.

I think addressing the naming is part one of a two- (or three-) part "usability" makeover for the engine api. Part two is more and better documentation. There are still several places where I, admittedly, don't know what's going on, and there's no api doc to clarify.

Thanks for your consideration. Here's the google doc that the attached pdf is based on. It's open for edits, so please go ahead and mark it up or add comments as you see fit.



I agree with your general proposal and with your assertion that we need a consistent convention for naming functions, types, and constants. I find your suggested changes easier to understand than the existing names in most cases.

I'm not crazy about the work-processing function names as they seem to disregard the grammar. Should they not all be pn_connection_* functions? Also, I find "head_delivery"/"delivery_next" to be an arbitrary and confusing swapping of noun and pronoun. Why not just "head_delivery" and "next_delivery"? That would be consistent with rule 10.

Looking again, I realize that "head_<type>" is an operation on connection and "<type>_next" is an operation on <type>. I withdraw my complaint about this.

I think we should gather some more input and make these changes before the first proton release.


Reply via email to