Developers Guide Coding Standards

Directory Structure

All source files go in src, all tests go in tests.

Both of these directories are flat, there is no further hierarchy.

File names

C source files and header files are all lower case with underscores where spaces would help readability:

chat_log.c

chat_log.h

Source file layout

C source files *.c should follow the following layout:

Filename and license information

System includes

Library includes

Profanity includes

Static variables

Static function prototypes

Functions

Static functions

Filename and license information

Example:

/* 
 * chat_log.c
 *
 * Copyright (C) 2012 James Booth <[email protected]>
 * 
 * This file is part of Profanity.
 *
 * Profanity is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * Profanity is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Profanity.  If not, see <http://www.gnu.org/licenses/>.
 *
 */

Includes

Includes start with system libraries, followed by a space, followed by third party libraries, followed by a space, followed by profanity includes:

#include <stdio.h>
#include <stdlib.h>

#include <glib.h>

#include "chat_log.h"
#include "common.h"
#include "util.h"

Static variables

Example:

static GHashTable *logs;
static GTimeZone *tz;

Static function prototypes

Static functions are always prefixed with an underscore by convention. Function prototypes always include parameter names (key, value, user_data) as well as types.

Return types are on the same line as the function name:

static void _close_file(gpointer key, gpointer value, gpointer user_data);

Functions

The return type is on a separate line to the function name, long function parameter lists are split across lines, with four spaces at the beginning of the next line.

The opening brace is on a new line.

There is one line of white space between function definitions.

gboolean
contact_list_add(const char * const name, const char * const show,
    const char * const status)
{
    return p_autocomplete_add(ac, p_contact_new(name, show, status));
}

When the return type is a pointer, the * is on the same line as the return type, not the function name:

char *
find_login(char *prefix)
{
    return p_autocomplete_complete(ac, prefix);
}

Static Functions

Rules are the same as for normal functions, with the addition that names start with an underscore:

static NCURSES_COLOR_T
_lookup_colour(const char * const colour)
{
    int i;
    for (i = 0; i < num_colours; i++) {
        if (strcmp(colours[i].str, colour) == 0) {
            return colours[i].colour;
        }
    }

    return -99;
}