mirror of
https://github.com/xen-project/xen.git
synced 2026-10-28 18:21:39 +01:00
George Dunlap
78ac45c9af
One of the common ways in which contributors trip up over the CODING_STYLE guides is by not putting a full stop at the end of a comment when there is only a single sentence. Calling these out is a waste of everybody's time: The full stop at the end of a comment with a single sentence (or a single phrase) adds absolutely nothing to the legibility of the code. Modify CODING_STYLE to allow comments with a single sentence or sentence fragment to either have a full stop or not, while making it clear that comments with multiple sentences must have a full stop at the end of each sentence. Signed-off-by: George Dunlap <george.dunlap@citrix.com> Acked-by: Ian Jackson <ian.jackson@citrix.com>
123 lines
3.1 KiB
Plaintext
123 lines
3.1 KiB
Plaintext
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. Comments containing a single sentence may end with a full
|
|
stop; comments containing several sentences must have a full stop
|
|
after each sentence.
|
|
|
|
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:
|
|
*/
|