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