motion/CODE_STANDARD

Formatting rules for Motion code.
Version 2.0 - 15 Jul 2008

Note: To understand them you must view this document with spaces and tabs
visible.

--------------------
RULE 1
Code is generally indented using 4 spaces

Example
/* allocate some memory and check if that succeeded or not. If it failed
 * do some error logging and bail out
 */
void * mymalloc(size_t nbytes)
{
    void *dummy = malloc(nbytes);
    if (!dummy) {
        printf("Could not allocate %llu bytes of memory!\n", (unsigned long long) nbytes);
        syslog(EMERG, TYPE_ALL, "%s: Could not allocate %llu bytes of memory!", 
               __FUNCTION__, (unsigned long long) nbytes);
        exit(1);
    }
    
    return dummy;
}

--------------------
RULE 2
If a line or statement is broken into two lines you will normally want the text
in the 2nd line to align with text in the first line.  The alignment is done
using spaces making the code on the following lines appear in a natural way below
the corresponding code above. Use common sense to enhance readability.

Example
/* allocate some memory and check if that succeeded or not. If it failed
 * do some error logging and bail out
 */
void * mymalloc(size_t nbytes)
{
    void *dummy = malloc(nbytes);
    if (!dummy) {
        printf("Could not allocate %llu bytes of memory!\n",
               (unsigned long long) nbytes);
        syslog(EMERG, TYPE_ALL,"Could not allocate %llu bytes of memory!",
               __FUNCTION__, (unsigned long long) nbytes);
        exit(1);
    }
    
    return dummy;
}

Example
    cnt->sql_mask = cnt->conf.sql_log_image * (FTYPE_IMAGE + FTYPE_IMAGE_MOTION) +
                    cnt->conf.sql_log_snapshot * FTYPE_IMAGE_SNAPSHOT +
                    cnt->conf.sql_log_mpeg * (FTYPE_MPEG + FTYPE_MPEG_MOTION) +
                    cnt->conf.sql_log_timelapse * FTYPE_MPEG_TIMELAPSE;



Example
    char msg[] = "This is a very long message which we would like to break"
                 "into two lines or more because otherwise the line gets"
                 "too long to read. We align them below each other for readability"

--------------------
RULE 3
Never use TABS to align anything. A tab may be 4 positions in one editor
and 8 in another. A space is always a space. 

--------------------
RULE 4
Functions should be written with this syntax.

GOOD EXAMPLE
/* Comment block
 * A comment block should be at least one line saying what the function does.
 * It is better to make several lines explaining what it does, what it takes
 * for arguments and what it returns. It is a bad idea to try to use tabs to
 * align text in the comment block
 */
type function_name(parameters)
{
    declarations
    declarations
    
    statements
    statements
}

Do not split the function declaration into two lines.
Do not put the '{' after the function declaration. Put it on an empty line
right after. Note that this rule is only for functions.

BAD EXAMPLE

type
function_name(parameters) {
    declarations
    declarations
    
    statements
    statements
}

--------------------
RULE 5
Blocks follow K&R.

GOOD EXAMPLE

if ((picture=fopen(cnt->conf.mask_file, "r"))) {
    cnt->imgs.mask=get_pgm(cnt, picture, cnt->imgs.width, cnt->imgs.height);
    fclose(picture);
} else {
    put_fixed_mask(cnt, cnt->conf.mask_file);
    printf("Hello world\n");
}


BAD EXAMPLE (even though Kenneth loves this one personally)

if ((picture=fopen(cnt->conf.mask_file, "r")))
{
    cnt->imgs.mask=get_pgm(cnt, picture, cnt->imgs.width, cnt->imgs.height);
    fclose(picture);
}
else
{
    put_fixed_mask(cnt, cnt->conf.mask_file);
    printf("Hello world\n");
}



GOOD EXAMPLE 

switch (expr) {
case ABC:
case DEF:
    statement;
    break;
case UVW:
    statement;
    break;
default:
    /* default case */
    statement;
}

BAD EXAMPLE

switch (expr) {
    case ABC:
    case DEF:
        statement;
    break;
    case UVW:
        statement;
    break;
    default:
        /* default case */
        statement;
}



--------------------
RULE 6
Whitespace.
To ensure that Motion code looks homogeneous and to enhance readability:
  1. Do not use a space before a comma
  2. Always leave at least one space after a comma
  3. Use one space between a block start statement and a '{'
  4. Do not use a space between a function name and the '('
  5. Use spaces to enhance readability (a non objective rule but at least
     think about it)
  6. The '*' for pointers should be just before the variable name with no
     space.

GOOD EXAMPLES
int function_name(int *par1, int par2, int par3) {
if (var1==2 || var2==3) {

BAD EXAMPLES
int function_name (int * par1 , int par2,int par3){
if (var1==2||var2==3){

--------------------
RULE 7
Comment your code
That's worth repeating - PLEASE, PLEASE comment your code.
We receive far too much code which is completely uncommented and where
variable names are short and say nothing about their function.
Use /* This style of comment for permament comments */ or
/*
 * This style of comment for comments which
 * require more that one line
 */
Use // this style comments for something you add temporarily while testing and
FIXME type comments. It is much easier to spot the temporary comments this way.

--------------------
RULE 8
Use variable names that say what the variable is used for.
Avoid x,t,vt type variable names.
Use names like image, image_buffer, image_height, output_buffer
Short names like i and j for loop index variable are a known good practice.
Variable and function names are in lower case. Use '_' to separate words.
MACROS are in uppercase.
camelCase (mix of upper and lower case) is not allowed because it creates too
many typos for many two finger typers.


--------------------

BEST PRACTICES
Not rules, but these suggestions make code easier to read.

Use lots of white space and empty lines to group code.
For example, large if statements are easier to read when there is an empty
line before and after them.

Use an empty line before a comment which describes the code lines below.

Always use spaces in statements like
thisvar->thismember>thisvar->thisothermember (bad)
thisvar->thismember > thisvar->thisothermember (good)

if (cnt->event_nr==cnt->prev_event||cnt->makemovie) (bad)
if (cnt->event_nr == cnt->prev_event || cnt->makemovie) (good)

frame_delay=(1000000L/cnt->conf.low_cpu)-frame_delay-elapsedtime; (bad)
frame_delay = (1000000L / cnt->conf.low_cpu) - frame_delay - elapsedtime; (good)


--------------------

This document can probably be enhanced more as time goes by.
Hope it helps developers to understand the ideas.

What happens if I do not follow the rules?
Your code will probably be accepted, but developers will have to spend a lot of
time rewriting the code to follow the standard. If this happens, he may make
a less-than-complimentary remark.  Please help the developers by at least trying
to follow the spirit of this document.  We all have our coding preferences, but
if Motion is coded in 40 different styles, readability (and at the end
quality) will become bad.