Hello
On 21.03.2011, at 13:44, Scott Wilson wrote: > 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. +1 When I wrote PHP connector, I was a bit confused too, this guid/id kept changing over the XML, creating naming conventions will definetly make things more clear. -- Raido > > 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 >
