mirror of
https://github.com/Motion-Project/motion.git
synced 2025-12-23 23:18:21 -05:00
256 lines
7.0 KiB
Plaintext
256 lines
7.0 KiB
Plaintext
Formatting rules for Motion code.
|
|
|
|
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 1A
|
|
Preprocessor statements such as #IF, #DEFINE, etc are to be indented
|
|
similar to normal code. These statements shall not be forced to start in column 1.
|
|
|
|
RULE 1B
|
|
When entire functions are enclosed in a #IF block, the functions should continue to
|
|
start in column 1.
|
|
|
|
|
|
--------------------
|
|
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 if it enhances the readability
|
|
of the statement. 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
|
|
}
|
|
|
|
For function declarations that span more than one line, a triple indent is
|
|
generally used for the second and subsequent lines to avoid excessive lines.
|
|
|
|
Do not stuff everything on a single line. Keep the line length to less than
|
|
100 characters. All variable names should be seen without having to scroll.
|
|
|
|
Do not put the '{' after the function declaration. Put it on an empty line
|
|
right after. Note that this rule is only for functions.
|
|
|
|
--------------------
|
|
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);
|
|
} else {
|
|
printf("Hello world\n");
|
|
}
|
|
|
|
|
|
BAD 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");
|
|
}
|
|
|
|
|
|
|
|
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 5A
|
|
if, while and for statements shall always use braces.
|
|
|
|
|
|
--------------------
|
|
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 but do not be verbose. Do not literally describe what
|
|
the code does unless it would not be obvious to someone who knows C.
|
|
|
|
BAD EXAMPLES
|
|
while (1) { /* 'Do forever' */
|
|
|
|
/*
|
|
* Now we increment the index
|
|
*/
|
|
indx++;
|
|
|
|
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
|
|
|
|
RULE 9
|
|
Break code into many smaller functions rather than one extremely long one.
|
|
It is easier to follow the flow when functions are simple and concise.
|
|
|
|
--------------------
|
|
|
|
BEST PRACTICES
|
|
Not rules, but these suggestions make code easier to read.
|
|
|
|
Use 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.
|
|
|
|
Please help the developers by at least trying to follow the spirit of this document. We all have our coding preferences, but
|