On Tue, Oct 2, 2012 at 3:51 PM, Justin Ross <jr...@redhat.com> wrote:
> I've now updated this document to include the Java naming delta: > > https://docs.google.com/**spreadsheet/ccc?key=** > 0ArGmVtK1EBOMdEw0bkp4OE5UOWpRR**kx3RzVoTjliX0E#gid=0<https://docs.google.com/spreadsheet/ccc?key=0ArGmVtK1EBOMdEw0bkp4OE5UOWpRRkx3RzVoTjliX0E#gid=0> > > More comments below. > > Justin > > > On Thu, 13 Sep 2012, Rafael Schloming wrote: > > On Thu, Sep 13, 2012 at 4:28 PM, Rajith Attapattu <rajit...@gmail.com >> >wrote: >> >> I must admit that when I looked at the code initially I did find it a >>> bit hard to navigate the code. >>> Once I figured out the pattern it was easy. >>> >>> >> I'm guessing Justin's view (sorry if I'm putting words in your mouth) is >> that there isn't a pattern. I differ slightly in that there is simply more >> than one pattern. ;-) >> > > I've updated the proposal to factor in the collections such as "work". The > change in summary is that I withdrew the proposed name changes in those > cases. > > > The core APIs follow an older pattern that didn't really hold up as more >> code was added. The newer stuff (e.g. the messenger and message APIs) >> definitely follow a pattern, and the portion of the lower level APIs added >> more recently follow that same pattern (e.g. pn_transport_bind vs >> pn_input). It definitely makes sense to go back and update the older >> portions of the lower level APIs prior to release. I'd say a good chunk of >> what Justin is proposing fits into this category, and some other stuff >> just >> needs to be documented better and would IMHO not warrant a name change. >> > > You've recently changed some of the engine names. Afaict, the changes are > the following two: > > * Put the type in the name (I'm way in favor of this) > * Use _get_ in some but not all accessors > > The latter one I find more inconsistent than it need be. You've > introduced _get_ in the name only where there is a corresponding setter. > Consider pn_connection_get_context versus pn_connection_error. Both are > accessors. Whether or not _get_ is in there, I would favor their working > the same. I believe the convention I'm following is actually the norm (for a good reason). The get/set_foo pattern is used for passive slots, i.e. it's a strong signal that if you call set_foo with a given value then get_foo will return that same value until set_foo is called again. Whereas dynamic/computed/derived values (something where it would never make sense to have a setter) are generally not prefixed by get. Some examples in Java would be things like Collection.size(), Object.hashCode(), Map.values(). I think this is a pretty valuable convention as it is a signal that you can't just grab the value and expect it not to change, you need to be aware of how it is computed and when it is necessary to access it again, e.g. in the collections case if you add stuff to the Collection then the size or hashCode may change, likewise with say pn_link_credit() or pn_link_queued() if you send messages on the link, then those quantities will dynamically change and you need to invoke the method again to get an up to date view of the given value. --Rafael
