Stefan Weil | 6576b74 | 2012-04-07 09:23:37 +0200 | [diff] [blame] | 1 | QEMU Coding Style |
aliguori | e68b98d | 2009-04-05 17:40:34 +0000 | [diff] [blame] | 2 | ================= |
| 3 | |
Blue Swirl | b646968 | 2011-01-20 20:58:56 +0000 | [diff] [blame] | 4 | Please use the script checkpatch.pl in the scripts directory to check |
| 5 | patches before submitting. |
| 6 | |
aliguori | e68b98d | 2009-04-05 17:40:34 +0000 | [diff] [blame] | 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 |
edgar_igl | 1cb499f | 2009-04-07 02:10:16 +0000 | [diff] [blame] | 16 | where they have been irreversibly coded into the syntax. |
aliguori | e68b98d | 2009-04-05 17:40:34 +0000 | [diff] [blame] | 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 | |
Anthony Liguori | c227f09 | 2009-10-01 16:12:16 -0500 | [diff] [blame] | 46 | Variables are lower_case_with_underscores; easy to type and read. Structured |
Peter Maydell | e3c52bf | 2012-01-13 20:29:49 +0000 | [diff] [blame] | 47 | type names are in CamelCase; harder to type but standing out. Enum type |
| 48 | names and function type names should also be in CamelCase. Scalar type |
Anthony Liguori | c227f09 | 2009-10-01 16:12:16 -0500 | [diff] [blame] | 49 | names are lower_case_with_underscores_ending_with_a_t, like the POSIX |
| 50 | uint64_t and family. Note that this last convention contradicts POSIX |
| 51 | and is therefore likely to be changed. |
| 52 | |
Avi Kivity | 77ac486 | 2010-03-11 16:48:43 +0200 | [diff] [blame] | 53 | When wrapping standard library functions, use the prefix qemu_ to alert |
| 54 | readers that they are seeing a wrapped version; otherwise avoid this prefix. |
| 55 | |
aliguori | e68b98d | 2009-04-05 17:40:34 +0000 | [diff] [blame] | 56 | 4. Block structure |
| 57 | |
| 58 | Every indented statement is braced; even if the block contains just one |
| 59 | statement. The opening brace is on the line that contains the control |
| 60 | flow statement that introduces the new block; the closing brace is on the |
| 61 | same line as the else keyword, or on a line by itself if there is no else |
| 62 | keyword. Example: |
| 63 | |
| 64 | if (a == 5) { |
| 65 | printf("a was 5.\n"); |
| 66 | } else if (a == 6) { |
| 67 | printf("a was 6.\n"); |
| 68 | } else { |
| 69 | printf("a was something else entirely.\n"); |
| 70 | } |
| 71 | |
Avi Kivity | 5f070c5 | 2011-07-25 18:55:53 +0300 | [diff] [blame] | 72 | Note that 'else if' is considered a single statement; otherwise a long if/ |
| 73 | else if/else if/.../else sequence would need an indent for every else |
| 74 | statement. |
| 75 | |
aliguori | e68b98d | 2009-04-05 17:40:34 +0000 | [diff] [blame] | 76 | An exception is the opening brace for a function; for reasons of tradition |
| 77 | and clarity it comes on a line by itself: |
| 78 | |
| 79 | void a_function(void) |
| 80 | { |
| 81 | do_something(); |
| 82 | } |
| 83 | |
| 84 | Rationale: a consistent (except for functions...) bracing style reduces |
| 85 | ambiguity and avoids needless churn when lines are added or removed. |
| 86 | Furthermore, it is the QEMU coding style. |