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 |
Jonathan Neuschäfer | 56bef85 | 2016-09-30 02:04:28 +0200 | [diff] [blame] | 12 | of approximately fifteen parsecs. Many a flamewar has been fought and |
aliguori | e68b98d | 2009-04-05 17:40:34 +0000 | [diff] [blame] | 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 | |
Wei Yang | 6ac1fca | 2019-03-04 15:16:30 +0800 | [diff] [blame] | 32 | 1.1 Multiline Indent |
| 33 | |
| 34 | There are several places where indent is necessary: |
| 35 | |
| 36 | - if/else |
| 37 | - while/for |
| 38 | - function definition & call |
| 39 | |
| 40 | When breaking up a long line to fit within line width, we need a proper indent |
| 41 | for the following lines. |
| 42 | |
| 43 | In case of if/else, while/for, align the secondary lines just after the |
| 44 | opening parenthesis of the first. |
| 45 | |
| 46 | For example: |
| 47 | |
| 48 | if (a == 1 && |
| 49 | b == 2) { |
| 50 | |
| 51 | while (a == 1 && |
| 52 | b == 2) { |
| 53 | |
| 54 | In case of function, there are several variants: |
| 55 | |
| 56 | * 4 spaces indent from the beginning |
| 57 | * align the secondary lines just after the opening parenthesis of the |
| 58 | first |
| 59 | |
| 60 | For example: |
| 61 | |
| 62 | do_something(x, y, |
| 63 | z); |
| 64 | |
| 65 | do_something(x, y, |
| 66 | z); |
| 67 | |
| 68 | do_something(x, do_another(y, |
| 69 | z)); |
| 70 | |
aliguori | e68b98d | 2009-04-05 17:40:34 +0000 | [diff] [blame] | 71 | 2. Line width |
| 72 | |
Paolo Bonzini | 8fbe3d1 | 2015-09-07 11:53:02 +0200 | [diff] [blame] | 73 | Lines should be 80 characters; try not to make them longer. |
| 74 | |
| 75 | Sometimes it is hard to do, especially when dealing with QEMU subsystems |
| 76 | that use long function or symbol names. Even in that case, do not make |
| 77 | lines much longer than 80 characters. |
aliguori | e68b98d | 2009-04-05 17:40:34 +0000 | [diff] [blame] | 78 | |
| 79 | Rationale: |
| 80 | - Some people like to tile their 24" screens with a 6x4 matrix of 80x24 |
| 81 | xterms and use vi in all of them. The best way to punish them is to |
| 82 | let them keep doing it. |
| 83 | - Code and especially patches is much more readable if limited to a sane |
| 84 | line length. Eighty is traditional. |
Paolo Bonzini | 8fbe3d1 | 2015-09-07 11:53:02 +0200 | [diff] [blame] | 85 | - The four-space indentation makes the most common excuse ("But look |
| 86 | at all that white space on the left!") moot. |
aliguori | e68b98d | 2009-04-05 17:40:34 +0000 | [diff] [blame] | 87 | - It is the QEMU coding style. |
| 88 | |
| 89 | 3. Naming |
| 90 | |
Anthony Liguori | c227f09 | 2009-10-01 16:12:16 -0500 | [diff] [blame] | 91 | Variables are lower_case_with_underscores; easy to type and read. Structured |
Peter Maydell | e3c52bf | 2012-01-13 20:29:49 +0000 | [diff] [blame] | 92 | type names are in CamelCase; harder to type but standing out. Enum type |
| 93 | names and function type names should also be in CamelCase. Scalar type |
Anthony Liguori | c227f09 | 2009-10-01 16:12:16 -0500 | [diff] [blame] | 94 | names are lower_case_with_underscores_ending_with_a_t, like the POSIX |
| 95 | uint64_t and family. Note that this last convention contradicts POSIX |
| 96 | and is therefore likely to be changed. |
| 97 | |
Avi Kivity | 77ac486 | 2010-03-11 16:48:43 +0200 | [diff] [blame] | 98 | When wrapping standard library functions, use the prefix qemu_ to alert |
| 99 | readers that they are seeing a wrapped version; otherwise avoid this prefix. |
| 100 | |
aliguori | e68b98d | 2009-04-05 17:40:34 +0000 | [diff] [blame] | 101 | 4. Block structure |
| 102 | |
| 103 | Every indented statement is braced; even if the block contains just one |
| 104 | statement. The opening brace is on the line that contains the control |
| 105 | flow statement that introduces the new block; the closing brace is on the |
| 106 | same line as the else keyword, or on a line by itself if there is no else |
| 107 | keyword. Example: |
| 108 | |
| 109 | if (a == 5) { |
| 110 | printf("a was 5.\n"); |
| 111 | } else if (a == 6) { |
| 112 | printf("a was 6.\n"); |
| 113 | } else { |
| 114 | printf("a was something else entirely.\n"); |
| 115 | } |
| 116 | |
Avi Kivity | 5f070c5 | 2011-07-25 18:55:53 +0300 | [diff] [blame] | 117 | Note that 'else if' is considered a single statement; otherwise a long if/ |
| 118 | else if/else if/.../else sequence would need an indent for every else |
| 119 | statement. |
| 120 | |
aliguori | e68b98d | 2009-04-05 17:40:34 +0000 | [diff] [blame] | 121 | An exception is the opening brace for a function; for reasons of tradition |
| 122 | and clarity it comes on a line by itself: |
| 123 | |
| 124 | void a_function(void) |
| 125 | { |
| 126 | do_something(); |
| 127 | } |
| 128 | |
| 129 | Rationale: a consistent (except for functions...) bracing style reduces |
| 130 | ambiguity and avoids needless churn when lines are added or removed. |
| 131 | Furthermore, it is the QEMU coding style. |
Eduardo Habkost | e939c6e | 2014-03-17 15:26:31 -0300 | [diff] [blame] | 132 | |
| 133 | 5. Declarations |
| 134 | |
Paolo Bonzini | 690a35e | 2015-06-19 09:28:13 +0200 | [diff] [blame] | 135 | Mixed declarations (interleaving statements and declarations within |
| 136 | blocks) are generally not allowed; declarations should be at the beginning |
| 137 | of blocks. |
| 138 | |
| 139 | Every now and then, an exception is made for declarations inside a |
| 140 | #ifdef or #ifndef block: if the code looks nicer, such declarations can |
| 141 | be placed at the top of the block even if there are statements above. |
| 142 | On the other hand, however, it's often best to move that #ifdef/#ifndef |
| 143 | block to a separate function altogether. |
Gonglei | 2bb0020 | 2014-08-11 21:00:51 +0800 | [diff] [blame] | 144 | |
| 145 | 6. Conditional statements |
| 146 | |
| 147 | When comparing a variable for (in)equality with a constant, list the |
| 148 | constant on the right, as in: |
| 149 | |
Wei Yang | 25d68ff | 2019-03-04 15:16:31 +0800 | [diff] [blame] | 150 | if (a == 1) { |
| 151 | /* Reads like: "If a equals 1" */ |
| 152 | do_something(); |
| 153 | } |
Gonglei | 2bb0020 | 2014-08-11 21:00:51 +0800 | [diff] [blame] | 154 | |
| 155 | Rationale: Yoda conditions (as in 'if (1 == a)') are awkward to read. |
| 156 | Besides, good compilers already warn users when '==' is mis-typed as '=', |
| 157 | even when the constant is on the right. |
Peter Maydell | 25ac5bb | 2017-02-03 17:58:42 +0000 | [diff] [blame] | 158 | |
| 159 | 7. Comment style |
| 160 | |
| 161 | We use traditional C-style /* */ comments and avoid // comments. |
| 162 | |
| 163 | Rationale: The // form is valid in C99, so this is purely a matter of |
| 164 | consistency of style. The checkpatch script will warn you about this. |
Vladimir Sementsov-Ogievskiy | 44c6d63 | 2017-07-31 19:01:32 +0300 | [diff] [blame] | 165 | |
Peter Maydell | 2948f0c | 2018-06-15 14:57:14 +0100 | [diff] [blame] | 166 | Multiline comment blocks should have a row of stars on the left, |
| 167 | and the initial /* and terminating */ both on their own lines: |
| 168 | /* |
| 169 | * like |
| 170 | * this |
| 171 | */ |
| 172 | This is the same format required by the Linux kernel coding style. |
| 173 | |
| 174 | (Some of the existing comments in the codebase use the GNU Coding |
| 175 | Standards form which does not have stars on the left, or other |
| 176 | variations; avoid these when writing new comments, but don't worry |
| 177 | about converting to the preferred form unless you're editing that |
| 178 | comment anyway.) |
| 179 | |
| 180 | Rationale: Consistency, and ease of visually picking out a multiline |
| 181 | comment from the surrounding code. |
| 182 | |
Vladimir Sementsov-Ogievskiy | 44c6d63 | 2017-07-31 19:01:32 +0300 | [diff] [blame] | 183 | 8. trace-events style |
| 184 | |
| 185 | 8.1 0x prefix |
| 186 | |
| 187 | In trace-events files, use a '0x' prefix to specify hex numbers, as in: |
| 188 | |
| 189 | some_trace(unsigned x, uint64_t y) "x 0x%x y 0x" PRIx64 |
| 190 | |
| 191 | An exception is made for groups of numbers that are hexadecimal by |
| 192 | convention and separated by the symbols '.', '/', ':', or ' ' (such as |
| 193 | PCI bus id): |
| 194 | |
| 195 | another_trace(int cssid, int ssid, int dev_num) "bus id: %x.%x.%04x" |
| 196 | |
| 197 | However, you can use '0x' for such groups if you want. Anyway, be sure that |
| 198 | it is obvious that numbers are in hex, ex.: |
| 199 | |
| 200 | data_dump(uint8_t c1, uint8_t c2, uint8_t c3) "bytes (in hex): %02x %02x %02x" |
| 201 | |
| 202 | Rationale: hex numbers are hard to read in logs when there is no 0x prefix, |
| 203 | especially when (occasionally) the representation doesn't contain any letters |
| 204 | and especially in one line with other decimal numbers. Number groups are allowed |
| 205 | to not use '0x' because for some things notations like %x.%x.%x are used not |
| 206 | only in Qemu. Also dumping raw data bytes with '0x' is less readable. |
| 207 | |
| 208 | 8.2 '#' printf flag |
| 209 | |
| 210 | Do not use printf flag '#', like '%#x'. |
| 211 | |
| 212 | Rationale: there are two ways to add a '0x' prefix to printed number: '0x%...' |
| 213 | and '%#...'. For consistency the only one way should be used. Arguments for |
| 214 | '0x%' are: |
| 215 | - it is more popular |
| 216 | - '%#' omits the 0x for the value 0 which makes output inconsistent |