root / CODING_STYLE @ e3e87df4
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. |