I agree we don't need complete parity in the naming. I think the important
test is whether one can easily map from one API to another, and perhaps
more importantly into a shared set of documentation.

As a comment on the general naming discussion I think there are really two
categories of things emerging here. One being discussion on very general
conventions that cover the whole API, and the other being very narrow
discussion on specific terms/names. It is *really* difficult to
follow/comment/discuss productively this latter category in the google doc
as there is really too much to be said to cram into a single spreadsheet
line, and it is difficult to follow changes/edits there. I think each of
the latter kind really need to be addressed in their own thread/JIRA and
that should probably start with a relatively complete description of what
the given thing is/does.

As for the general conventions, I believe the C code currently follows all
of the ones listed in the google doc including the crossed out line 4, with
the possible exception of 2 and 10 which I think are really pointed at a
few very specific choices and probably better discussed in that context. I
think as a general convention given the propensity to noun verbs and verb
nouns in english both 2 and 10 could better be summarized as names should
not be cryptic or confusing. Of course most people probably have no clue
what I just said because they don't have the googledoc in front of them. ;-)

--Rafael

On Fri, Oct 5, 2012 at 9:01 AM, Rob Godfrey <rob.j.godf...@gmail.com> wrote:

> >> >
> >>
> >> So... personally I don't have quite the horror of extra characters
> >> that certain others do... and I think prepending an "is" on methods
> >> that are returning a boolean is a reasonable deviation from the
> >> pattern established in the C.
> >
> >
> > The C actually does follow the is_ convention, e.g.:
> >
> >   bool pn_message_is_durable(pn_message_t *msg)
> >   int pn_message_set_durable(pn_message_t *msg, bool durable)
> >
> > I believe the only place where it deviates from this is for dynamically
> > computed values like. pn_delivery_writable() which is consistent with the
> > convention I described before regarding dynamically computed values.
>
> Yes - I just thing that this is less common / clear than using *is*
> consistently.  Ultimately I don't think it's vital that the method
> naming is exactly identical between Java and C (it won't be anyway).
> To me XXX.writable() is imperative not inquisitive and thus confusing
> as a method name.
>
> >
> >> I can buy that there are certain methods where the get/set pairing
> >> doesn't really imply the actual semantics that the methods have.  In
> >> general for the "count" type variables that cannot directly be set, I
> >> think getXxxCount() also works, but I'm also happy with the current
> >> xxx() style.
> >
> >
> > My problem with the getXxxCount() pattern is that it doesn't really fit
> with
> > all the terms, e.g. getCreditCount() doesn't really make sense. It would
> > have to be something more like getPotentialDeliveryCount(), but even this
> > wouldn't be sufficient as there is more than one potential delivery count
> > associated with a link (e.g. available vs credit).
> >
>
> Sure - but I think there is a subtle difference between a potential
> getCredit() and a potential getQueued(). Intuitively you expect Credit
> to be a count, whereas Queued might be a count or it might be a data
> structure.
>
> My main argument for using a get* convention is that it can make it
> easier for people to find the relevant methods ... people will
> generally be looking for methods beginning with "get" when they want
> to retrieve a value.  Furthermore, if like me you use an IDE you can
> start typing get... and a range of possible auto-completions will
> appear, which will then jog your memory or at least point you where to
> look.  With no such get prefix, the methods to retrieve values will be
> scattered across the alphabet and less easy to scan in this way.
>
> > In general beyond the basic conventional stuff which seems fairly
> > uncontroversial, I think we actually need more documentation to properly
> > motivate and discuss naming changes. Names really are a
> mnemonic/pointer/key
> > into a mental model, and it really helps to have both a shared and
> accurate
> > mental model when discussing them. Flow control in particular is a fairly
> > complex domain that requires keeping multiple time-lagged viewpoints in
> your
> > head as they exchange numerous formally defined quantities. Without a
> solid
> > mental model pretty much any names will seem opaque and useless. To use
> an
> > analogy, getting every math library in the world and renaming the sine
> > function to getOppositeToHypotenuseRatio, isn't really going to make
> anyone
> > understand trigonometry. Of course I realize there is a tradeoff here,
> but I
> > think one of the better ways to figure out where that tradeoff lies is to
> > actually document the concepts as then it becomes clearer how a name will
> > impact the total economy of expression.
> >
>
> I'm completely for putting in a whole lot more documentation. I think
> we should be open to renaming in the light of that exercise. I'm also
> relaxed if there are differences between the conventions used between
> the Java and the C as long as there are no fundamental differences in
> naming the properties (whether things have get or set prefixed on them
> doesn't fundamentally seem to be of huge consequence to me).
>
> >>
> >> There are a couple of areas where I think the naming definitely needs
> >> work, in particular hostname: The "local" hostname is actually the
> >> hostname that is desired to be chosen at the remote endpoint, while
> >> the "remote" hostname is the hostname that the remote endpoint desires
> >> at the local side.
> >
> >
> > The C code uses a slightly different convention for local/remote stuff
> and
> > in this case it actually helps a little, rather than doing local_foo and
> > remote_foo it does foo and remote_foo. So at least we don't end up with
> > something called local_hostname that doesn't actually refer to the local
> > hostname, however the same problem is there for the remote hostname.
> >
>
> Yeah - I don't really have any issue bringing the Java into line for
> the general local/remote pattern... but I don't think it actually
> helps any for hostname.
>
> >> Of the proposals, I think Delivery.update is less wrong than
> >> "acknowledge" ... the update may not be an acknowledgement but some
> >> other form of state change. Also rescind_credit is not really the
> >> semantics of drain (if there are messages available then the peer
> >> should send them, not simply cancel the credit).
> >
> >
> > +1
> >
> >> Source and Target - currently the API is incomplete here - a proper
> >> definition of these types is needed which is why in the Java I've
> >> currently got these as Source/Target Address.  The Source and Target
> >> types should be properly defined with APIs which allow for the setting
> >> of other attributes than just the address.
> >
> >
> > This definitely needs to change. One of the complications here is that
> the
> > transactional spec actually defines completely different
> sources/targets, so
> > it's not as simple as just defining the specific fields in the messaging
> > specification, we need some way to swap in an entirely different kind of
> > source/target.
> >
>
> Yeah - obviously this is somewhat easier in Java where I just have
> objects that implement the necessary interfaces.
>
> -- Rob
>
> > --Rafael
> >
>

Reply via email to