Re: [Qemu-devel] [PATCH] Document Qemu coding style

[Blue Swirl]

On 3/30/09, Avi Kivity <address@hidden> wrote:
> With the help of some Limoncino I noted several aspects of the Qemu coding
>  style, particularly where it differs from the Linux coding style as many
>  contributors work on both projects.

Ok, I'm armed with some Foster's.

>
>  Signed-off-by: Avi Kivity <address@hidden>
>  ---
>   CODING_STYLE |   77 
> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>   1 files changed, 77 insertions(+), 0 deletions(-)
>   create mode 100644 CODING_STYLE
>
>  diff --git a/CODING_STYLE b/CODING_STYLE
>  new file mode 100644
>  index 0000000..54fdeff
>  --- /dev/null
>  +++ b/CODING_STYLE
>  @@ -0,0 +1,77 @@
>  +Qemu Coding Style
>  +=================
>  +
>  +1. Whitespace
>  +
>  +Of course, the most important aspect in any coding style is whitespace.
>  +Crusty old coders who have trouble spotting the glasses on their noses
>  +can tell the difference between a tab and eight spaces from a distance
>  +of approximately fifteen parsecs.  Many a flamewar have been fought and
>  +lost on this issue.
>  +
>  +Qemu indents are four spaces.  Tabs are never used, except in Makefiles
>  +where they have been irreversibly coded into the syntax by some moron.
>  +Spaces of course are superior to tabs because:
>  +
>  + - You have just one way to specify whitespace, not two.  Ambiguity breeds
>  +   mistakes.
>  + - The confusion surrounding 'use tabs to indent, spaces to justify' is 
> gone.
>  + - Tab indents push your code to the right, making your screen seriously
>  +   unbalanced.
>  + - Tabs will be rendered incorrectly on editors who are misconfigured not
>  +   to use tab stops of eight positions.
>  + - Tabs are rendered badly in patches, causing off-by-one errors in almost
>  +   every line.
>  + - It is the Qemu coding style.

Never leave whitespace at the end of line, it annoys the Quilt. Empty
lines at the end of file just make files bigger.

>  +
>  +2. Line width
>  +
>  +Lines are 80 characters wide plus some slop.  Try to fit your code into
>  +eighty characters, but if it makes a snippet particularly ugly, allow
>  +yourself some slack.  Don't overdo it though.
>  +
>  +Rationale:
>  + - Some people like to tile their 24" screens with a 6x4 matrix of 80x24
>  +   xterms and use vi in all of them.  The best way to punish them is to
>  +   let them keep doing it.
>  + - Code and especially patches is much more readable if limited to a sane
>  +   line length.  Eighty is traditional.
>  + - It is the Qemu coding style.
>  +
>  +3. Naming
>  +
>  +Variables are lower_case_with_underscores; easy to type and read.  
> Structured
>  +type names are in CamelCase; harder to type but standing out.  Scalar type
>  +names are lower_case_with_underscores_ending_with_a_t, like the Posix
>  +uint64_t and family.
>  +
>  +Typedefs are used to eliminate the redundant 'struct' keyword.  It is the
>  +Qemu coding style.
>  +
>  +4. Block structure
>  +
>  +Every indented statement is braced; even if the block contains just one
>  +statement.

I'd remove this, braces are not used consistently for one statement blocks.

>  The opening brace is on the line that contains the control
>  +flow statement that introduces the new block; the closing brace is on the
>  +same line as the else keyword, or on a line by itself if there is no else
>  +keyword.  Example:
>  +
>  +    if (a == 5) {
>  +        printf("a was 5.\n");
>  +    } else if (a == 6) {
>  +        printf("a was 6.\n");
>  +    } else {
>  +        printf("a was something else entirely.\n");
>  +    }
>  +
>  +An exception is the opening brace for a function; for reasons of tradition
>  +and clarity it comes on a line by itself:
>  +
>  +    void a_function(void)
>  +    {
>  +        do_something();
>  +    }
>  +
>  +Rationale: a consistent (except for functions...) bracing style reduces
>  +ambiguity and avoids needless churn when lines are added or removed.
>  +Furthermore, it is the Qemu coding style.

No, this is the K&R style. Quoting linux/Documentation/CodingStyle:

Heretic people all over the world have claimed that this inconsistency
is ...  well ...  inconsistent, but all right-thinking people know that
(a) K&R are _right_ and (b) K&R are right.  Besides, functions are
special anyway (you can't nest them in C).

Cheers!