Attachment 46820 Details for Bug 37095 – Write about best-practices for interface names in the same place they're defined

[patch] Write about best-practices for interface names in the same place they're defined

0001-Write-about-best-practices-for-interface-names-in-th.patch (text/plain), 2.57 KB, created by Simon McVittie on 2011-05-17 09:11:43 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2011-05-17 09:11:43 UTC

Size: 2.57 KB

patch

obsolete

>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 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 @@
> 	    <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>
>-- 
>1.7.5.1
>

Actions: View | Splinter Review

Attachments on bug 37095: 46820 | 46821 | 46822 | 46823 | 46824 | 46825 | 46826 | 46827 | 46828 | 126931

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.