From cf32940b2ab18a760f28f1318cfbb77b7f8dff66 Mon Sep 17 00:00:00 2001
From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Tue, 17 May 2011 17:04:39 +0100
Subject: [PATCH] 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 file changed, 26 insertions(+)

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 @@
 	    <listitem><para>Interface names must not exceed the maximum name length.</para></listitem>
           </itemizedlist>
         </para>
+
+        <para>
+          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.
+        </para>
+
+        <para>
+          For instance, if the owner of <literal>example.com</literal> is
+          developing a D-Bus API for a music player, they might define
+          interfaces called <literal>com.example.MusicPlayer1</literal>,
+          <literal>com.example.MusicPlayer1.Track</literal> and
+          <literal>com.example.MusicPlayer1.Seekable</literal>.
+        </para>
+
+        <para>
+          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.
+        </para>
       </sect3>
       <sect3 id="message-protocol-names-bus">
         <title>Bus names</title>
-- 
2.7.4