[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Xen-devel] [PATCH] Document the current coding style conventions.



>>> On 14.03.12 at 18:27, David Vrabel <david.vrabel@xxxxxxxxxx> wrote:
> From: David Vrabel <david.vrabel@xxxxxxxxxx>
> 
> Based on a version originally posted in 2007.
> http://lists.xen.org/archives/html/xen-devel/2007-06/msg00070.html 
> 
> Signed-off-by: David Vrabel <david.vrabel@xxxxxxxxxx>
> ---
>  docs/misc/coding_style.txt |  100 
> ++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 100 insertions(+), 0 deletions(-)
>  create mode 100644 docs/misc/coding_style.txt
> 
> diff --git a/docs/misc/coding_style.txt b/docs/misc/coding_style.txt
> new file mode 100644
> index 0000000..2ece1ec
> --- /dev/null
> +++ b/docs/misc/coding_style.txt
> @@ -0,0 +1,100 @@
> +Coding Style for the Xen Hypervisor
> +===================================
> +
> +This coding style is used for C code that is part of the Xen
> +Hypervisor itself, or part of the associated user space tools.  Guest
> +operating system code may use the native coding style of that code
> +base.  The goal of this file is to document the main points of the Xen
> +coding style, particularly where they differ from normal Linux
> +convention.
> +
> +libxl has its own coding style documented in tools/libxl/CODING_STYLE.
> +
> +Indentation
> +-----------
> +
> +Indenting uses spaces, not tabs - in contrast to Linux.  An indent
> +level consists of four spaces.  Code within blocks is indented by one
> +extra indent level.  The enclosing braces of a block are indented the
> +same as the code _outside_ the block.  e.g.
> +
> +void fun(void)
> +{
> +    /* One level of indent. */
> +
> +    {
> +        /* A second level of indent. */
> +    }
> +}

An exception should probably be declared for code pulled over from
Linux almost unmodified.

Further, Linux'es document doesn't say anything about the
indentation of long function parameter and argument lists. Do we
want to leave this to the authors' taste as well?

> +
> +White space
> +-----------
> +
> +Space characters are used to spread out logical statements, such as in
> +the condition of an if or while.  Spaces are placed between the
> +keyword and the brackets surrounding the condition, between the
> +brackets and the condition itself, and around binary operators (except
> +the structure memory operators, '.' and '->'). e.g.
> +
> +if ( (wibble & wombat) == 42 )
> +{
> +    ...
> +
> +There should be no trailing white space at the end of lines (including
> +after the opening /* of a comment block).
> +
> +Bracing
> +-------
> +
> +Braces ('{' and '}') are usually placed on a line of their own, except
> +for the do/while loop.  This is unlike the Linux coding style and
> +unlike K&R.  do/while loops are an exception. e.g.:
> +
> +if ( condition )
> +{
> +    /* Do stuff. */
> +}
> +
> +while ( condition )
> +{
> +    /* Do stuff. */
> +}
> +
> +do {
> +    /* Do stuff. */
> +} while ( condition );
> +
> +etc.
> +
> +Braces should be omitted for blocks with a single statement. e.g.,

"may" is probably the better term, as there's quite a number of
examples where this is not the case. (I would personally like the
more strict form you gave, as I dislike those superfluous braces).

> +
> +if ( condition )
> +    single_statement();
> +
> +Comments
> +--------
> +
> +Only C style /* ... */ comments are to be used.  C++ style // comments
> +should not be used in submitted code.  Multi-word comments should
> +begin with a capital letter and end with a full stop.
> +
> +/*
> + * Example, multi-line comment block.
> + *
> + * Note beginning and end markers on separate lines and leading '*'.
> + */

The statement prior to the example only mentions multi-word
comments, whereas the example is a multi-line one. Perhaps the
statement could be extended to demand the /* and */ to be on
separate lines for multi-line comments.

Nothing is being said on maximum line length. In particular it'd be nice
to clarify whether we want to follow Linux'es relatively recent (in 3.1)
move towards not breaking up printk() messages (which I'm in favor
of, and would even volunteer to clean up, as I really dislike having to
guess how long lines got broken up in the sources - it wasn't just
once that I had to make a couple of tries until I managed to locate a
certain message).

Jan

> +
> +Emacs local variables
> +---------------------
> +
> +A comment block containing local variables for emacs is permitted at
> +the end of files.  It should be:
> +
> +/*
> + * Local variables:
> + * mode: C
> + * c-file-style: "BSD"
> + * c-basic-offset: 4
> + * indent-tabs-mode: nil
> + * End:
> + */
> -- 
> 1.7.2.5
> 
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@xxxxxxxxxxxxx 
> http://lists.xen.org/xen-devel 



_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel


 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.