MouthOS Coding Standards

When coding on MouthOS these are the expected standards.

All .c, .h files should have the following at the top:

/* MouthOS (wombat) Kernel
 * (C) Copyright 2008. Michael F Clarke. All Rights Reserved.
 */

After this block you may add personal copyright information, licence information, author information etc. For example:

/* File Version: 0.0.1
 * Author: Joe Bloggs
 * EMail: joe@bloggs.com
 *
 * This file deals with blah...
 * etc as you wish.
 */

All .s files should have the following at the top:

 ; MouthOS (wombat) Kernel
 ; (C) Copyright 2008. Michael F Clarke. All Rights Reserved.

Again, as with the .c and .h files, feel free to add your own banner after the main banner.

All functions should be commented and should be in the following format:

/*
 * This function does blah. It is used by blah.
 *
 * param size this is blah.
 * param i this is another blah.
 *
 * returns integer representing blah.
 */
int
my_cool_kernel_function(int size, int i) 
{

        i++;
        size += i;
        return size;
}

Functions that are to return void should do so as follows:

(void)
my_fun_to_ret_void
{
        ...
}

When writing if statements, for loops etc that have only a single instruction always to the following:

for ( i = 0 ; i < 10 ; i++)
        j += i;

if (i >= 10)
        return j;

Do not do any of the following:

for ( i = 0 ; i < 10 ; i++) {
        j += i;
}

for ( i = 0 ; i < 10 ; i++ )
{
        j += i;
}

Avoid comments within C code, except for at the top of functions and never re-write the code. This is an example of a useless comment:

/*
 * This function is used to increment i.
 *
 * param i The initial value to be incremented.
 * param j The value to increment by.
 *
 * return i + j.
 */
int
inc_val(int i, int j)
{
 
        /***** BAD COMMENTS BEGIN! ******/

        /* Loop through j all the way to zero. */ 
        for ( j ; j > 0 ; j-- )
                /* let i = i + 1. */
                i++;

        /* return the new value of i. */
        return i;
}