xen/tools/libxl/CODING_STYLE

Libxenlight Coding Style
========================

Blatantly copied from qemu and linux with few modifications.


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.

Libxenlight indents are four spaces.  Tabs are never used, except in
Makefiles where they have been irreversibly coded into the syntax.
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 libxenlight coding style.

Do not leave whitespace dangling off the ends of lines.


2. Line width

Lines are limited to 75-80 characters.

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 libxenlight coding style.


3. Naming

C is a Spartan language, and so should your naming be.  Unlike Modula-2
and Pascal programmers, C programmers do not use cute names like
ThisVariableIsATemporaryCounter.  A C programmer would call that
variable "tmp", which is much easier to write, and not the least more
difficult to understand.

HOWEVER, while mixed-case names are frowned upon, descriptive names for
global variables are a must.  To call a global function "foo" is a
shooting offense.

GLOBAL variables (to be used only if you _really_ need them) need to
have descriptive names, as do global functions.  If you have a function
that counts the number of active users, you should call that
"count_active_users()" or similar, you should _not_ call it "cntusr()".

Encoding the type of a function into the name (so-called Hungarian
notation) is brain damaged - the compiler knows the types anyway and can
check those, and it only confuses the programmer.

LOCAL variable names should be short, and to the point.  If you have
some random integer loop counter, it should probably be called "i".
Calling it "loop_counter" is non-productive, if there is no chance of it
being mis-understood.  Similarly, "tmp" can be just about any type of
variable that is used to hold a temporary value.

Local variables used to store return values should have descriptive name
like "rc" or "ret". Following the same reasoning the label used as exit
path should be called "out" or "error".

Variables, type names and function names are
lower_case_with_underscores.
Type names and function names use the prefix libxl__ when internal to
libxenlight and libxl_ when exported in libxl.h.
Xl should avoid using libxl_ and libxl__ as prefix for its own function
names.

When wrapping standard library functions, use the prefix libxl_ to alert
readers that they are seeing a wrapped version; otherwise avoid this prefix.

Typedefs are used to eliminate the redundant 'struct' keyword.
It is the libxenlight coding style.


4. Statements

Don't put multiple statements on a single line.
Don't put multiple assignments on a single line either.
Error code paths with an if statement and a goto or a return on the same
line are allowed. Examples:

    if (rc) goto out;
    if (rc < 0) return;

Libxenlight coding style is super simple.  Avoid tricky expressions.


5. Block structure

Every indented statement is braced apart from blocks that contain just
one statement.
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.  Examples:

    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");
    }

    if (a == 5)
        printf("a was 5.\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 libxenlight coding style.