Created attachment 46820 [details] [review] 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" Created attachment 46821 [details] [review] [PATCH 2/9] Formally define a unique connection name and a well-known bus name Created attachment 46822 [details] [review] [PATCH 3/9] Describe best-practices for naming well-known bus names Created attachment 46823 [details] [review] [PATCH 4/9] Describe conventional naming of methods and signals Created attachment 46824 [details] [review] [PATCH 5/9] Describe conventional naming of errors Created attachment 46825 [details] [review] [PATCH 6/9] Briefly mention why to namespace object-paths Created attachment 46826 [details] [review] [PATCH 7/9] Remove the old, vague Naming Conventions section The defining instance of each namespaced term now contains notes on conventional naming. Created attachment 46827 [details] [review] [PATCH 8/9] Describe best practices for property names, and recommend against dash-separated-words Related to <https://bugs.freedesktop.org/show_bug.cgi?id=20948> whose conclusion seemed to be that anything is allowed, but CamelCase is considerably more interoperable. Created attachment 46828 [details] [review] [PATCH 9/9] Cross-reference from the glossary to interface names etc. Looks all good to me. Might be good though to add an explicit blurb about that people should never use the object path "/" (or is that already mentioned somewhere?). But maybe that's something to bring up in a different bug? (In reply to comment #11) > Looks all good to me. Thanks, fixed in git for 1.5.10. > Might be good though to add an explicit blurb about that people should > never use the object path "/" Yeah, perhaps. Leaving this open, I'll write some wording if you don't get there first. Created attachment 126931 [details] [review] spec: Recommend against using ‘/’ for object paths As discussed in http://0pointer.de/blog/projects/versioning-dbus.html and in https://dbus.freedesktop.org/doc/dbus-api-design.html, un-versioned object paths make it hard to work out which interface a signal was emitted from. Clarify this in the specification to try and avoid people making this mistake. Thanks, applied. Fixed in git for 1.11.6 (spec 0.29). |
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.
The D-Bus Specification says: D-Bus namespaces are all lowercase and correspond to reversed domain names, as with Java. e.g. "org.freedesktop" but this is currently quite well hidden, and nothing really defines what we mean by "namespace". Under "Valid Object Paths", we should mention that it's conventional, and recommended, to start with a reversed domain name (for the reasons mentioned in <http://0pointer.de/blog/projects/versioning-dbus.html>, and so that you can implement several D-Bus APIs designed by different people in the same service). Under "Valid Names", we should mention that it's conventional and strongly recommended to start with a reversed domain name. Under "Bus Names" we should mention the same thing for well-known names.