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