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
