API usability is important and deserves attention.

Take, for instance, DeliveryState versus Disposition. That only serves to confuse people. It's a difference that has no content. I also think link.drained and link.offered are very unclear.

I've found the whole process of proposing API review dispiriting. You can, of course, take it or leave it. I in no way wish to claim I have better choices. I only wish to point out things that might deserve more deliberation.



Endpoint state


    Existing C name:    PN_LOCAL_UNINIT
    Proposed C name:    PN_LOCAL_UNINITIALIZED
    Existing Java name: EndpointState.UNINITIALIZED
    Proposed Java name:

    One api has the remote-local distinction in one bitset, and one does
    not.  Is this difference desirable?


    Existing C name:    PN_REMOTE_UNINIT
    Proposed C name:    PN_REMOTE_UNINITIALIZED
    Existing Java name: EndpointState.UNINITIALIZED
    Proposed Java name:

    Personally, I'm at ease with UNINIT as an abbreviation here



    Existing C name:    pn_disposition_t
    Proposed C name:
    Existing Java name: DeliveryState
    Proposed Java name: Disposition

    DeliveryState vs. Disposition.  A good example of a confusing
    difference.  I have a slight preference for DeliveryState (it's self-
    explanatory), but matching is the main thing.


    Existing C name:    pn_delivery_tag_t
    Proposed C name:
    Existing Java name: [anonymous byte array]
    Proposed Java name:




    Existing C name:    pn_session_connection
    Proposed C name:    pn_session_get_connection

    According to Rafi's system, this should have _get_.



    Existing C name:    pn_link_session
    Proposed C name:    pn_link_get_session



    Existing C name:    pn_link_drained
    Proposed C name:    pn_link_drain_credit [?]
    Existing Java name: Sender.drained
    Proposed Java name: Sender.drainCredit [?]

    I can't tell what's going on here.  I particularly dislike
    pn_link_drained and _offered.  They look like predicates but have no
    return value.



    Existing C name:    pn_link_flow
    Proposed C name:    pn_link_issue_credit
    Existing Java name: Receiver.flow
    Proposed Java name: Receiver.issueCredit

    Consider pn_link_increase_credit, pn_link_issue_credit; working in the
    word "credit" somehow would help a lot


    Existing C name:    pn_link_drain
    Proposed C name:    pn_link_rescind_credit
    Existing Java name: Receiver.drain
    Proposed Java name: Receiver.rescindCredit

    Consider pn_link_decrease_credit, pn_link_rescind_credit



    Existing C name:    pn_delivery_link
    Proposed C name:    pn_delivery_get_link


    Existing C name:    pn_delivery_local_state
    Proposed C name:    pn_delivery_state
    Existing Java name: Delivery.getLocalState
    Proposed Java name: Delivery.state

    "Local" is not used elsewhere for local/remote distinctions


    Existing C name:    pn_delivery_update
    Proposed C name:    pn_delivery_acknowledge
    Existing Java name: Delivery.disposition
    Proposed Java name: Delivery.acknowledge

    Do calls to delivery.update correspond one-to-one to
    delivery.updated?  The naming implies a symmetry that I'm not sure
    is there.

On Thu, 13 Dec 2012, Justin Ross (JIRA) wrote:


Justin Ross commented on PROTON-26:

That's really not the case.  Rejecting it is fine, but it's mostly gone 
undiscussed.  That's partly my fault.  A post to the mailing list with 
highlights suitable for inline comments is incoming.

Engine api naming proposal

                Key: PROTON-26
                URL: https://issues.apache.org/jira/browse/PROTON-26
            Project: Qpid Proton
         Issue Type: Improvement
         Components: proton-c, proton-j
           Reporter: Justin Ross
           Assignee: Rafael H. Schloming
             Labels: api
            Fix For: 0.2

        Attachments: engine-naming-01.patch, 
proton-engine-naming-proposal-2.pdf, proton-engine-naming-proposal-3.pdf


This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira

Reply via email to