root / CODING_STYLE @ 7fee199c
History | View | Annotate | Download (2.9 kB)
1 |
Qemu Coding Style |
---|---|
2 |
================= |
3 |
|
4 |
Please use the script checkpatch.pl in the scripts directory to check |
5 |
patches before submitting. |
6 |
|
7 |
1. Whitespace |
8 |
|
9 |
Of course, the most important aspect in any coding style is whitespace. |
10 |
Crusty old coders who have trouble spotting the glasses on their noses |
11 |
can tell the difference between a tab and eight spaces from a distance |
12 |
of approximately fifteen parsecs. Many a flamewar have been fought and |
13 |
lost on this issue. |
14 |
|
15 |
QEMU indents are four spaces. Tabs are never used, except in Makefiles |
16 |
where they have been irreversibly coded into the syntax. |
17 |
Spaces of course are superior to tabs because: |
18 |
|
19 |
- You have just one way to specify whitespace, not two. Ambiguity breeds |
20 |
mistakes. |
21 |
- The confusion surrounding 'use tabs to indent, spaces to justify' is gone. |
22 |
- Tab indents push your code to the right, making your screen seriously |
23 |
unbalanced. |
24 |
- Tabs will be rendered incorrectly on editors who are misconfigured not |
25 |
to use tab stops of eight positions. |
26 |
- Tabs are rendered badly in patches, causing off-by-one errors in almost |
27 |
every line. |
28 |
- It is the QEMU coding style. |
29 |
|
30 |
Do not leave whitespace dangling off the ends of lines. |
31 |
|
32 |
2. Line width |
33 |
|
34 |
Lines are 80 characters; not longer. |
35 |
|
36 |
Rationale: |
37 |
- Some people like to tile their 24" screens with a 6x4 matrix of 80x24 |
38 |
xterms and use vi in all of them. The best way to punish them is to |
39 |
let them keep doing it. |
40 |
- Code and especially patches is much more readable if limited to a sane |
41 |
line length. Eighty is traditional. |
42 |
- It is the QEMU coding style. |
43 |
|
44 |
3. Naming |
45 |
|
46 |
Variables are lower_case_with_underscores; easy to type and read. Structured |
47 |
type names are in CamelCase; harder to type but standing out. Scalar type |
48 |
names are lower_case_with_underscores_ending_with_a_t, like the POSIX |
49 |
uint64_t and family. Note that this last convention contradicts POSIX |
50 |
and is therefore likely to be changed. |
51 |
|
52 |
When wrapping standard library functions, use the prefix qemu_ to alert |
53 |
readers that they are seeing a wrapped version; otherwise avoid this prefix. |
54 |
|
55 |
4. Block structure |
56 |
|
57 |
Every indented statement is braced; even if the block contains just one |
58 |
statement. The opening brace is on the line that contains the control |
59 |
flow statement that introduces the new block; the closing brace is on the |
60 |
same line as the else keyword, or on a line by itself if there is no else |
61 |
keyword. Example: |
62 |
|
63 |
if (a == 5) { |
64 |
printf("a was 5.\n"); |
65 |
} else if (a == 6) { |
66 |
printf("a was 6.\n"); |
67 |
} else { |
68 |
printf("a was something else entirely.\n"); |
69 |
} |
70 |
|
71 |
An exception is the opening brace for a function; for reasons of tradition |
72 |
and clarity it comes on a line by itself: |
73 |
|
74 |
void a_function(void) |
75 |
{ |
76 |
do_something(); |
77 |
} |
78 |
|
79 |
Rationale: a consistent (except for functions...) bracing style reduces |
80 |
ambiguity and avoids needless churn when lines are added or removed. |
81 |
Furthermore, it is the QEMU coding style. |