From cf32940b2ab18a760f28f1318cfbb77b7f8dff66 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Tue, 17 May 2011 17:04:39 +0100 Subject: [PATCH 1/9] Write about best-practices for interface names in the same place they're defined I'm deliberately using a hypothetical API from example.com, rather than a real API, to avoid perpetuating these over-simplifications any further than they've spread already: - "namespaces start with org.freedesktop" - "namespaces start with org" - "interfaces are defined by their sole implementation" - "services have one object implementing one interface" - "interfaces always behave like classes" - "interfaces are always noun phrases" - "there is a freedesktop.org D-Bus API for screensavers" --- doc/dbus-specification.xml | 26 ++++++++++++++++++++++++++ 1 files changed, 26 insertions(+), 0 deletions(-) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 324d8b9..8207810 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -1183,6 +1183,32 @@ Interface names must not exceed the maximum name length. + + + Interface names should start with the reversed DNS domain name of + the author of the interface (in lower-case), like interface names + in Java. It is conventional for the rest of the interface name + to consist of words run together, with initial capital letters + on all words ("CamelCase"). Several levels of hierarchy can be used. + It is also a good idea to include the major version of the interface + in the name, and increment it if incompatible changes are made; + this way, a single object can implement several versions of an + interface in parallel, if necessary. + + + + For instance, if the owner of example.com is + developing a D-Bus API for a music player, they might define + interfaces called com.example.MusicPlayer1, + com.example.MusicPlayer1.Track and + com.example.MusicPlayer1.Seekable. + + + + D-Bus does not distinguish between the concepts that would be + called classes and interfaces in Java: either can be identified on + D-Bus by an interface name. + Bus names -- 1.7.5.1