Telepathy Wiki

This coding style is (or should be) used for all the core Telepathy components, notably telepathy-glib, libtelepathy, telepathy-gabble and telepathy-stream-engine.

These are guidelines only; there are always exceptional circumstances. Consistency and readability are usually the most important considerations.

C

Filenames

Don't put a common prefix on all files in a project - we like our tab completion to work (<telepathy-glib/connection.h> is good, <telepathy-glib/tp-connection.h> would be bad)
If you're writing a library where headers will be included like <foo/bar.h>, put the headers (and probably corresponding sources) in a directory called foo (probably top-level).
- This way the library and its examples/tests can be compiled with -I$(top_srcdir) -I$(top_builddir) (or possibly -I$(top_srcdir)/src -I$(top_builddir)/src or something) and use #include <foo/bar.h> throughout
Code generation tools (a la telepathy-glib) typically go in ./tools
The darcs 'boringfile' preference (the filename used as a .cvsignore equivalent) is typically set to '_boring'
autoconf macros usually go in ./m4. This requires AC_CONFIG_MACRO_DIR([m4]) in configure.ac and ACLOCAL_AMFLAGS = -I m4 in the top-level Makefile.am (use both).

#includes

If you're going to #include "config.h", do that first, in case it defines things like "inline".

Next, #include the header in which this .c file's API is declared. This guarantees that all public headers are self-contained.

Next, #define any libc feature-test macros you need (_GNU_SOURCE etc.) and #include any C/POSIX standard library headers you need, in alphabetical order.

Next, #include any headers you need from non-standard libraries (GLib, Gtk, telepathy-glib, Avahi, ...) in alphabetical order.

Finally, #include any private (non-installed) headers from the library or program you're writing.

For example:

/* Example 1: foo.c
 * ... insert copyright etc. here ... 
 */
#include "config.h"

#include "foo.h"

#ifndef _POSIX_C_SOURCE
#define _POSIX_C_SOURCE 200112L /* for posix_memalign */
#endif
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>

#include <avahi-common/address.h>
#include <glib-object.h>
#include <telepathy-glib/bar.h>

#define DEBUG_FLAG DEBUG_FOO
#include "bar.h"
#include "debug.h"
#include "foobar.h"

(Try to avoid using non-standard functions that need feature test macros - I've just used posix_memalign here for the sake of an example.)

Layout

Indentation is GNU-style:

/* Example 2 */
while (foo)
  {
    if (badger != NULL)
      bar ();

    if (mushroom != NULL)
      {
        do_stuff ();
      }
    else
      {
        do_more_stuff ();
        do_yet_more_stuff ();
      }
  }

Function declarations are in the style:

/* Example 3 */
static void badger_mushroom (Mushroom *self, const gchar *reason,
    gint another_param, ..., gpointer omg_so_many_params);

but function definitions are in the style:

/* Example 4 */
static void
badger_mushroom (Mushroom *self,
                 const gchar *reason,
                 gint another_param,
                 ...
                 gpointer omg_so_many_params)
{
  ...
}

(Rationale: that way you can grep for ^function_name and you'll only find the definition, without any clutter caused by declarations).

Two blank lines between function definitions.
Function calls have a space after the function name.

Long lines (>79 chars) should be wrapped with a four-space indent, like this:

   /* Example 5 */
   static void
   do_some_stuff (Mushroom *self)
   {
     do_some_other_stuff (self, 123, 42, TP_TYPE_MUSHROOM,
         OTHER_STUFF_ADD_BADGERS | OTHER_STUFF_NO_SNAKES,
         "this example has too many parameters",
         CARROTS | HANDBAGS | CHEESE,
         TABLET, BRICK, POTATO, LLAMA);
   }

Exception: definitions (but not declarations) have exactly one parameter per line, with second and subsequent lines indented to match first line, like Example 4

Naming

Functions allocating memory should end in _new.

Misc

Use glib types for preference.
Casts look like:

Fungus *fungus;
Mushroom *mushroom;

mushroom = MUSHROOM (fungus);
/* or if there's no suitable asserting macro or if the cast is from
 * a subclass to a superclass, */
mushroom = (Mushroom *) fungus;

Use gchar * for strings that should be freed with g_free, char * for strings that should be freed with e.g. avahi_free.
Use the G_GNUC_* function annotations where possible.
Use GSlice allocation for non-GObjects where possible.
Use g_set_error instead of g_error_new where possible.
Never use explicit comparisons with TRUE and FALSE for booleans - if have_value is a gboolean, use "if (have_value)" instead of "if (have_value == TRUE)".
Always use explicit comparisons for non-boolean integers and for pointers - if i is an integer and p is a pointer, use "if (i != 0)" instead of "if (i)", and "if (p != NULL)" instead of "if (p)".

Python

See PEP 8.

Indentation should always be 4 spaces.

Emacs C Mode

Adding the following to your .emacsrc creates a Telepathy style for you:

(defun telepathy-c-initialization-hook ()
  (c-add-style "telepathy" 
  '("gnu"
    (indent-tabs-mode . nil)
    (c-offsets-alist
     (arglist-intro . 4)
     (arglist-cont-nonempty . tp-lineup-arglist-cont)))))

(defun tp-lineup-arglist-cont (langelem)
  (let (syntax)
    (save-excursion 
      (goto-char (cdr langelem))
      (setq syntax (c-guess-basic-syntax)))
    (if (assq 'topmost-intro-cont syntax)
        ;; Lineup arglist in function definitions 
        (c-lineup-arglist-intro-after-paren langelem)
      ;; 'topmost-intro is used in declarations
      4)))

(add-hook 'c-initialization-hook 'telepathy-c-initialization-hook)

You can also set telepathy style as default:

(setq c-default-style "telepathy")

Vim Configuration

Adding the following to your .vimrc should help with adherence to these guidelines:

set cino=>2s,{1s,n-s,^-s
autocmd FileType python setl tw=78 ts=4 sts=4 sw=4 et
autocmd FileType c      setl tw=78 ts=2 sts=2 sw=2 et

Style

C