File: CODE_STANDARD

package info (click to toggle)
motion 4.3.2-1
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, bullseye, sid
  • size: 4,020 kB
  • sloc: ansic: 26,372; makefile: 83; sh: 59
file content (248 lines) | stat: -rw-r--r-- 7,032 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
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.