Code Style Guide

Please follow these guidelines when writing new code in Pidgin, Finch, and libpurple. If you are writing a patch against code that violates these standards, please fix violations in that block of code, but don't reformat entire files!

In general we try to follow K&R coding style in most of our code. See examples below.

Braces

• Prefer braces around single line blocks. Reasons:
  • Reduces chances of bugs, if someone adds code at the same indentation level without realizing that there are no braces.
  • Smaller diffs when adding code to an existing single-line block.
• For functions, structs, typedefs, etc. braces start on their own lines.
• For if, while, do, for, etc. braces start on the same line.
• Braces end on their own lines, indented equally as the start of the block.

static void
some_function(int x, int y)
{
        if (x > y) {
                do_something();
        } else {
                do_something_else();
        }

        for (i = 0; i < x; i++) {
                ...
        }
};

Indentation

• We use tab for indentation (and it's preferable that you use 8-space tabs in your editor).
• When wrapping long lines, tab indent to the start of the statement then add two more tabs.

Whitespace

• Avoid multiple statements on a single line.
• Avoid putting statements on the same line as their if, while, for, etc.
• A space (or a newline) after ; , =
• A space in front of = and ( except for function calls. e.g.:

  for (i = 0; i < x; i++) {
          ...
  }
  
  some_function(var1, var2);
  

• No whitespace at the end of line

Comments

• Code should be self-documenting. If the code you're writing does something non-obvious, add a comment to help future developers understand what's happening.
• Function declarations in header files must be documented. See our existing header files for examples. (If you find an undocumented or poorly documented function, please submit a patch to fix it!)
• Documenting static (non-exported) functions is good, but not essential.
• Only use C89 comments, not C++/C99 one-line comments:

// don't use this style--we don't like it

/* Use this kind of comment for a single line. */

/* And if you have a comment spanning multiple lines,
 * have a neat column of stars to the left!
 */

Function Definitions

• There should be a newline between the return type of the function and the function's name.
• Wrap parameters sensibly, preferably around 80 characters or so.
• Opening brace should be on a new line.
• Functions not called from other files should be declared static.
• Functions called from other files should be listed in a .h file.

GtkWidget *
do_some_magic_thing(int foo, gchar *bar)
{
        ...
}

Variables

• Prefer declaring each variable on its own line. This makes diffs easier to read and reduces churn. It also makes the code more clear when one variable is given an initial value but another is not.
• Use const for variables that don't need to change or be deallocated.
• Avoid assigning variables in conditions unless it leads to simpler logic, e.g.:

  /* Don't do this: */
  if ((written = write(fd, buf, len)) < len) {
          ...
  }
  
  /* Do this -- it's easier to read and leads to
   * cleaner diffs when things change: */
  written = write(fd, buf, len);
  if (written < len) {
          ...
  }
  
  /* But this is often ok, because the alternative might be unwieldy: */
  while (has_next = get_next()) {
          ...
  }