thr3ads.net - Xen devel - [PATCH v2] Document the coding style conventions. [Mar 2012]

If this information is useful, please help other people find it:
Share via:

David Vrabel

2012-Mar-19 11:34 UTC

[PATCH v2] Document the coding style conventions.

From: David Vrabel <david.vrabel@citrix.com>

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@citrix.com>
---
Changes since v1:
  - renamed to CODING_STYLE
  - intro text from Ian C.
  - line length section
  - expanded bracing example.

Not changed since v1:
  - braces around single statement still ''should'' not
''may''.
---
 CODING_STYLE |  120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 120 insertions(+), 0 deletions(-)
 create mode 100644 CODING_STYLE

diff --git a/CODING_STYLE b/CODING_STYLE
new file mode 100644
index 0000000..95842e3
--- /dev/null
+++ b/CODING_STYLE
@@ -0,0 +1,120 @@
+Coding Style for the Xen Hypervisor
+==================================+
+The Xen coding style described below is the coding style used by the
+Xen hypervisor itself (xen/*) as well as various associated low-level
+libraries (e.g. tools/libxc/*).
+        
+An exception is made for files which are imported from an external
+source. In these cases the prevailing coding style of the upstream
+source is generally used (commonly the Linux coding style).
+        
+Other parts of the code base may use other coding styles, sometimes
+explicitly (e.g. tools/libxl/CODING_STYLE) but often implicitly (Linux
+coding style is fairly common). In general you should copy the style
+of the surrounding code. If you are unsure please ask.
+
+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. */
+    }
+}
+
+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 access 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).
+
+Line Length
+-----------
+
+Lines should be less than 80 characters in length.  Long lines should
+be split at sensible places and the trailing portions indented.
+
+User visible strings (e.g., printk() messages) should not be split so
+they can searched for more easily.
+
+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. */
+}
+else
+{
+    /* Other stuff. */
+}
+
+while ( condition )
+{
+    /* Do stuff. */
+}
+
+do {
+    /* Do stuff. */
+} while ( condition );
+
+etc.
+
+Braces should be omitted for blocks with a single statement. e.g.,
+
+if ( condition )
+    single_statement();
+
+Comments
+--------
+
+Only C style /* ... */ comments are to be used.  C++ style // comments
+should not be used.  Multi-word comments should begin with a capital
+letter and end with a full stop.
+
+Multi-line comment blocks should start and end with comment markers on
+separate lines and each line should begin with a leading ''*''.
+
+/*
+ * Example, multi-line comment block.
+ *
+ * Note beginning and end markers on separate lines and leading
''*''.
+ */
+
+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

Stefano Stabellini

2012-Mar-19 12:20 UTC

head link

Re: [PATCH v2] Document the coding style conventions.

On Mon, 19 Mar 2012, David Vrabel wrote:> From: David Vrabel <david.vrabel@citrix.com>
> 
> 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@citrix.com>
> ---
> Changes since v1:
>   - renamed to CODING_STYLE
>   - intro text from Ian C.
>   - line length section
>   - expanded bracing example.
> 
> Not changed since v1:
>   - braces around single statement still ''should'' not
''may''.
> ---
>  CODING_STYLE |  120
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 120 insertions(+), 0 deletions(-)
>  create mode 100644 CODING_STYLE
> 
> diff --git a/CODING_STYLE b/CODING_STYLE
> new file mode 100644
> index 0000000..95842e3
> --- /dev/null
> +++ b/CODING_STYLE
> @@ -0,0 +1,120 @@
> +Coding Style for the Xen Hypervisor
> +==================================> +
> +The Xen coding style described below is the coding style used by the
> +Xen hypervisor itself (xen/*) as well as various associated low-level
> +libraries (e.g. tools/libxc/*).
> +        
> +An exception is made for files which are imported from an external
> +source. In these cases the prevailing coding style of the upstream
> +source is generally used (commonly the Linux coding style).
> +        
> +Other parts of the code base may use other coding styles, sometimes
> +explicitly (e.g. tools/libxl/CODING_STYLE) but often implicitly (Linux
> +coding style is fairly common). In general you should copy the style
> +of the surrounding code. If you are unsure please ask.
> +
> +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. */
> +    }
> +}
> +
> +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 access 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).
> +
> +Line Length
> +-----------
> +
> +Lines should be less than 80 characters in length.  Long lines should
> +be split at sensible places and the trailing portions indented.
> +
> +User visible strings (e.g., printk() messages) should not be split so
> +they can searched for more easily.
> +
> +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. */
> +}
> +else
> +{
> +    /* Other stuff. */
> +}
> +
> +while ( condition )
> +{
> +    /* Do stuff. */
> +}
> +
> +do {
> +    /* Do stuff. */
> +} while ( condition );
> +
> +etc.
> +
> +Braces should be omitted for blocks with a single statement. e.g.,
> +
> +if ( condition )
> +    single_statement();
> +
> +Comments
> +--------
> +
> +Only C style /* ... */ comments are to be used.  C++ style // comments
> +should not be used.  Multi-word comments should begin with a capital
> +letter and end with a full stop.
> +
> +Multi-line comment blocks should start and end with comment markers on
> +separate lines and each line should begin with a leading
''*''.
> +
> +/*
> + * Example, multi-line comment block.
> + *
> + * Note beginning and end markers on separate lines and leading
''*''.
> + */
> +
> +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:
> + */
vim comments should be allowed too?
We don''t want to start a religious war, do we? ;-)

It think that the equivalent of the emacs comment would be:

/* vim: ts=4 et sw=4 */

Ian Campbell

2012-Mar-19 12:24 UTC

head link

Re: [PATCH v2] Document the coding style conventions.

On Mon, 2012-03-19 at 12:20 +0000, Stefano Stabellini
wrote:> On Mon, 19 Mar 2012, David Vrabel wrote:
> > From: David Vrabel <david.vrabel@citrix.com>
> > 
> > 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@citrix.com>
Acked-by: Ian Campbell <ian.campbell@citrix.com>

As usual with these things I''m of the opinion that having a document in
place which can be improved is more important than getting it 100% right
first time.

[...]> > +/*
> > + * Local variables:
> > + * mode: C
> > + * c-file-style: "BSD"
> > + * c-basic-offset: 4
> > + * indent-tabs-mode: nil
> > + * End:
> > + */
> 
> vim comments should be allowed too?
> We don''t want to start a religious war, do we? ;-)
Absolutely not ;-)

Just waiting for the nano fans to come out of the woodwork...
> 
> It think that the equivalent of the emacs comment would be:
> 
> /* vim: ts=4 et sw=4 */

Xen devel - Mar 2012 - [PATCH v2] Document the coding style conventions.

[PATCH v2] Document the coding style conventions.

Re: [PATCH v2] Document the coding style conventions.

Re: [PATCH v2] Document the coding style conventions.