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.

Justin

---

Endpoint state

  PN_LOCAL_UNINIT

    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?

  PN_REMOTE_UNINIT

    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

Types

  pn_disposition_t

    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.

  pn_delivery_tag_t

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

    DeliveryTag?

Session

  pn_session_connection

    Existing C name:    pn_session_connection
    Proposed C name:    pn_session_get_connection

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

Link

  pn_link_session

    Existing C name:    pn_link_session
    Proposed C name:    pn_link_get_session

Sender

  pn_link_drained

    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.

Receiver

  pn_link_flow

    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

  pn_link_drain

    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

Delivery

  pn_delivery_link

    Existing C name:    pn_delivery_link
    Proposed C name:    pn_delivery_get_link

  pn_delivery_local_state

    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

  pn_delivery_update

    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:


   [ 
https://issues.apache.org/jira/browse/PROTON-26?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13531571#comment-13531571
 ]

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


See 
https://docs.google.com/spreadsheet/ccc?key=0ArGmVtK1EBOMdEw0bkp4OE5UOWpRRkx3RzVoTjliX0E#gid=0

--
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