Statistics
| Branch: | Revision:

root / CODING_STYLE @ feature-archipelago

History | View | Annotate | Download (3.1 kB)

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