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.
https://docs.google.com/spreadsheet/ccc?key=0ArGmVtK1EBOMdEw0bkp4OE5UOWpRRkx3RzVoTjliX0E#gid=0
Thanks!
Justin
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.
I think we should gather some more input and make these changes before
the first proton release.
-Ted
