= 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 below for specific examples:


== 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.

{{{
#!c
static void
some_function(int x, int y)
{
        if (x > y) {
            return;
        }

        for (i = 0; i < x; i++) {
                /* the code here, indented by a tab */
        }
};
}}}


== 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 ==
 * A space (or a newline) after ; , =
 * A space in front of = and ( except for function calls. e.g.:
{{{
#!c
for (i = 0; i < x; i++) ..

some_function(var1, var2);
}}}
 * No whitespace at the end of line


== Comments ==
 * A comment or two in the static (non-exported) functions is good, but not essential.
 * Function declarations in header files must be documented. See our other header files for examples. (If you find an undocumented or poorly documented function, please do submit a patch fixing it!)
 * Only use C89 comments, not C++/C99 one-line comments:

{{{
#!c
// 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.
 * As mentioned above, the opening brace should be on a new line.

For example:

{{{
#!c
GtkWidget *
do_some_magic_thing(int foo, gchar *bar)
{
        /* misc, other */
}


== Variable Declarations ==
 * Prefer declaring each variable on its own line. This makes diffs easier to read and reduces churn.
 * Use const for variables that don't need to change or be deallocated.