DBus properties naming rules

[Simon McVittie]

(I'm not sure why this thread wasn't on the D-Bus mailing list... see xdg
archives for history.)

On Tue, 08 Sep 2009 at 15:07:06 -0600, Aaron J. Seigo wrote:
> we're talking about the allowed character set, not case or stylistic format. 
> it's a slightly different matter, as the former says which characters are 
> legal and the latter suggest how to use those characters. (to state the 
> obvious)

Actually, I'd go a little further than that, and say that new D-Bus APIs
SHOULD (but definitely not MUST) use capitalized words without punctuation
(e.g. GetNameOwner) for D-Bus method, signal and property names.

This isn't a mandatory requirement for use of D-Bus, but it should be in some
list of "how to write a D-Bus API that does not violate least-astonishment",
along with common interoperability things like:

* reply to each method call exactly once, with either a method reply or an
  error
* don't reply to things that are not method calls
* don't send method replies or errors except as replies to method calls,
  and don't send them to destinations other than the method call's sender
* don't implement more than one of (method, signal, property) with the same
  name on the same interface
* don't use varargs (which can't be represented in Introspect() output)
* don't overload methods
* implement Introspectable on every object

(The D-Bus specification doesn't actually forbid violating any of those, and
neither does libdbus in most cases, but IMO specifications that want to be
interoperable should obey them.)

Rationale: given that D-Bus' goals include interoperability between languages
and runtimes, the method (etc.) names exposed on the bus should be independent
of the language used to implement the services; we already have a convention
for how methods and signals are named (the same as in the bus daemon), and
using that convention for properties is sensible.

I don't think we want a situation where D-Bus APIs originating from KDE have
methods (etc.) like doSomeStuff, APIs originating from GNOME or Python have
methods (etc.) like do_some_stuff, and only APIs that always intended to be
environment-independent (like Telepathy) have DoSomeStuff.

If bindings want to map from the D-Bus convention, or some other abstract API
definition, to the language's conventional case-convention, then they're free
to do that (for instance, in telepathy-glib you use a generated wrapper,
tp_cli_channel_call_get_interfaces(), to call the GetInterfaces() method).

In Telepathy we've found it useful to use what we call "Ugly_Case" (initial
caps with underscores) in abstract descriptions of API, since it's equally
easy to map that to D-Bus-style names (delete underscores), Qt-style names
(force everything before the first underscore to lower case then delete
underscores), or GLib-style names (force to lower-case).

    Simon