On 21 Mar 2011, at 11:15, Michael Aram wrote: > Dear Wookie-Community, > >
(I'll leave the connectors issue for those more familiar with them to comment on...) > * Cleaning up the whole identifier mess by enforcing naming conventions * > > In Wookie (as in most software), a great number of different > identifiers come into play. There are Widget GUIDs (i.e. URL-Strings), > Wookie "internal" Widget IDs (i.e. integers), WidgetInstance > identifiers (i.e. Strings), and so on. In variables names and in code > comments, different names are used for the same concept. For example, > the Widget GUID is often called "guid" in the documentation, but the > XML (/wookie/widgets?all=true) uses "identifier" as attribute name - > the Wookie internal id comes as "id" in this XML. The WidgetInstance > XML (whose root element is called "widgetdata" instead of > "widgetinstance" btw - any reason for that?) (no, I've no idea why its called that) > uses the element (not > attribute, btw) "identifier", this identifier string is then applied > to the WidgetInstances "id" (not "identifier") property by the > connector framework. Of course, there is also the WidgetInstance's > "url", which also somehow "uniquely identifies" a widget instance. > > This can result in confusion when working with the code - an evidence > for this is for example, that the Ruby connector framework (in > contrast to the PHP implementation, which follows the "semantic bug" > of the Java version) does not use the identifier property provided by > the WidgetInstance's XML at all (see: > http://svn.apache.org/repos/asf/incubator/wookie/trunk/connector/ruby/wookie/WookieConnectorService.rb). > > Therefore, I would recommend to create a small set of "naming > conventions" for those critical variable names, like "always call a > widget's guid "widgetGuid" when writing code/documentation" or "never > use the word "widget" when refering to a widget-instance"; and to do a > small refactoring before the first Wookie release. +1 on creating naming conventions for these terms; I've noticed the same thing myself. I don't know about doing it before the first release - I think we ought do this for the second release (0.9.1) rather than delay the initial release further. See also https://issues.apache.org/jira/browse/WOOKIE-34 and http://incubator.apache.org/wookie/strawman-for-082.html (where we can also propose changing the instance XML representation in line with agreed conventions) Michael - would you like to submit a draft text for the conventions? It sounds like you've got a good handle on the issue. > Looking forward to see some of you in Bolton this week :-) > > Regards > Michael
