Formatting rules for Motion code.

Motion is coded in accordance with the K&R formatting style.  Indentation is
TAB based but done so that formatting never depends upon how a text editor or
text viewer represents a TAB.

Some people assume a tab is always at multiples of 8 positions, but many
others choose to use 4 or 6.  If the source file does not take this into
consideration, the text alignment looks awful when viewed with a tab setting
which differs from the original.

We want to ensure that no matter which motion source file you look at, the
style looks the same.  In order to do that, the Motion project enforces some
additional rules.

Here are the basic rules.

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

--------------------
RULE 1
Code is generally indented using TABS

Example1

/* 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(LOG_EMERG, "Could not allocate %llu bytes of memory!", (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. This alignment must be
done by following these rules:
    1. On the continuation line, first you put tabs to reach the same
       indentation level as the line above.
    2. Then you align with SPACES until the text in the 2nd line is aligned
       with the desired text above.

Example 2
/* 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(LOG_EMERG, "Could not allocate %llu bytes of memory!",
		       (unsigned long long) nbytes);
		exit(1);
	}
	
	return dummy;
}

Never do this:
WRONG EXAMPLE
		printf("Could not allocate %llu bytes of memory!\n",
			(unsigned long long) nbytes);

The reason is that the 3rd tab will be shown with whatever width is given by
the editor or viewer. The result is that you never know where the text ends.
The alignment of the text is very important for the readability of the code.


GOOD 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;

BAD 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;


GOOD 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"

BAD 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"

Again, a different tab setting destroys alignment.

--------------------
RULE 3
Never use TABS to align anything other than the start of line indentation.

WRONG EXAMPLE
 *
 *	cnt		Pointer to the motion context structure
 *	level		logging level for the 'syslog' function
 *			(-1 implies no syslog message should be produced)
 *	errno_flag	if set, the log message should be followed by the
 *			error message.
 *	fmt		the format string for producing the message
 *	ap		variable-length argument list
 
THE CORRECT WAY
 *
 *      cnt             Pointer to the motion context structure
 *      level           logging level for the 'syslog' function
 *                      (-1 implies no syslog message should be produced)
 *      errno_flag      if set, the log message should be followed by the
 *                      error message.
 *      fmt             the format string for producing the message
 *      ap              variable-length argument list

Again the reason is that the aligment of the text when using tabs is
depending on the tab settings in editor or viewer.

BAD EXAMPLE

void function_a(void someparam)
{
	int	myvar1		/* explanation */
	char	hellomyvar2	/* explanation */

In this bad example the variable names will not align if the tab setting is
not 8 positions. At 4 positions, for example, the variable names (as well as
the comments) are no longer aligned.

GOOD EXAMPLE
void function_a(void someparam)
{
	int myvar1              /* explanation */
	char hellomyvar2        /* explanation */

Don't try and align variables. It does not become very readable when one type
is int and another is unsigned long long int. There is too much white space
between a short type name and the variable name. Comments after the variable
name look good, provided that you use spaces to align them.

--------------------
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.
Kenneth Lavrsen actually hates the K&R syntax, but it is the most generally
accepted way, it was the way Motion was coded when Kenneth took over the
project and it is now the way in which we will continue.

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");
}

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

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

GOOD 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 names are in lower case. Use '_' to separate words.
MACROS are in uppercase.


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

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