interface changes - naming convention

Martin Klang <[email protected]> Thu, 14 Oct 2004 05:24:53 +0100
Newsgroups gmane.text.xml.o-xml
Message-ID <[email protected]>
Me again - with a request for opinions!

The interfaces of the core types of o:XML as well as the library code 
have so far been designed to be short-and-sweet. This however has lead 
to potentially confusing situations such as:
Element.attribute(Name name): get an attribute
Element.attribute(Name name, Node value): set an attribute
Now if you add another function that sets an attribute, that takes 
simply an Attribute node, then things get worse:
Element.attribute(Attribute value): set an attribute

A slightly more verbose, arguably less pretty, definitely less 
confusing alternative would be to use Java-style getters and setters:
Element.getAttribute(Name name): get an attribute
Element.setAttribute(Attribute value): set an attribute

Camel-casing may have its own drawbacks - getAValue() for example looks 
pretty weird, and setHTTPURL() vs setHttpUrl() seems a loose/loose. 
Still these special cases are less commonly occurring than the whole 
get/set confusion. Also note that o:XML already uses camel-casing for 
certain functions such as String.substringBefore().

One could argue that since o:XML uses XPath extensively, we should 
adopt the XPath/XSLT naming convention of all lower-case, hyphenated 
names. That would get us:
Element.get-attribute(Name name): get an attribute
Element.set-attribute(Attribute value): set an attribute
get-a-value()
set-http-url()
String.substring-before(String str): just like XPath

etc.

There are naming standards for example for Java, and XML Schema, that 
could be leveraged. In the case of Java it is supposed to be camel-case 
with all-uppercase acronyms, and a lower-case first character for 
methods and upper-case for classes, but this isn't followed to the 
letter, so to speak, eg java.net.HttpURLConnection is irregular.

I would ideally like to align all interfaces for the 1.1.0 release, 
rather than postpone the inevitable, so it is essential to get your 
feedback asap - reply now! The discussion could / should be extended to 
Type as well as function names, and what to do about those XPath 
functions.

regards, looking forward to your comments,

/m