cstyle.txt

开放源码的编译器open watcom 1.6.0版的源代码

switch( x ) {
case 1:
    // code for case 1
    break;
case 2:
    // code for case 2
    break;
default:
    // default case
}

"case" and "default" are viewed as part of "switch" for indentation
purposes.

If the code for the cases in the switch statement is exceptionally
short, you can format the entire case statement on a single line, such
as the following:

switch( x ) {
case 1: // tiny code;   break;
case 2: // more code;   break;
}

If you wish to create a nested code block for a case statement (for
example to declare some local variables in C code), do so like the
following:

switch( x ) {
case 1:
    {
        int local_var;
        // code for case 1
    }
    break;
    ...
}

It is advisable to include a default action for a switch statement, but
this can be left out for efficiency's sake.

If falling through is used in switch statements, it is highly
recommended that a comment to that effect is added, such as this:

switch( x ) {
case 1:
    // code for case 1
case 2;                 // Note fallthrough!
    // code for case 2
    break;
default:
    // default case
}

Goto Statements
---------------

Occasionally, it is reasonable to use goto statements. The corresponding
labels should be indented to the same level as the braces enclosing both
goto and label.

switch( argv[0][1] ) {
...
case 'D':
    if( !optionsPredefine( &argv[0][2] ) )
        goto errInvalid;
    break;
...
default:
errInvalid:
...
}

Usage of gotos should be kept to minimum and is not recommended. In the
vast majority of cases, the same effect can be achieved using structured
programming constructs in a much safer way.

Expressions
-----------

When formatting expressions, try to use spaces and parentheses to
enhance the readability of the expression---splitting it over multiple
lines if necessary to make it more readable. Do not format expressions
without any spaces between binary operators and their operands. For
example:

    x = (y + 10) - 240 * (20 / (t + my_func()));

rather than

    x=(y+10)-240*(20/(t+my_func()));

If parentheses contain an expression, there should be no space
after the opening and before the closing parenthesis. Combined with the
preceding guidelines, code should be formatted this way:

if( (a || my_func( b )) && ((c = my_other_func( 1 + x )) == 42) ) {
    // do something
}

That is, for parentheses that are parts of control statements and function
calls, spaces should be after the opening and before the closing parenthesis,
but spaces should not be used with parentheses that simply group expressions
together.

Return statements
-----------------

In functions that return a value, the return expression should be placed
in parentheses. For example:

return( i + 1 );

or

return( TRUE );

In other words, format return statements as if 'return' was a name of a
function.

Operator sizeof
---------------

The same applies to the sizeof operator, that is, parentheses should be used
as if sizeof was a function. For example:

i = sizeof( void * );


Variable Declarations
---------------------

Don't declare multiple variables in one declaration that spans lines.
Instead start a new declaration on each line. For example, instead of
this:

    int foo,
        bar;

write either this (recommended form):

    int foo;
    int bar;

or this:

    int foo, bar;

Global Variables Within a Module
--------------------------------

Any global variables and external global variables must be declared at
the start of the source file. Globals variables that are private to the
source module should be declared with the static type modifier. External
global variables will always be declared in a separate header file, and
the definition of the variable will be located in one source module
without the static modifier. When formatting global variables, try to
format them such that the names of the variables align on "tab stop"
columns. For example:

// 45678 1 234567  column counter for illustration.
int         my_var1;
long        my_var2;
my_structue my_structure = {
    ...
};

Local variables
---------------

Declarations of local variables should be formatted similarly to those
of global variables, as detailed above. For example:

void foo( void )
// 45678 1 234567  column counter for illustration.
{
    int         my_var1;
    long        my_var2;
    void const  *my_ptr;

    // code follows here
}

Note that the declaration block is separated from the first statement in
the function by a blank line.

Comments and Commenting Style
-----------------------------

Commenting code is extremely important. Comments serve as an aid to the
human readers of source code; they are a form of engineering etiquette.
Comments should always be used to clarify otherwise obscure code.
However do not comment too liberally. If the code itself describes
concisely what is happening, do NOT provide a comment explaining the
obvious! Comments should always be neat and readable - haphazardly
placed comments are almost as bad as haphazardly formatted source code.

Comments should also be used to document the purpose of obscure or
non-trivial functions (a non-trivial function is one of more than a few
lines) and what inputs and outputs the function deals with. Please refer
to the section on Function Bodies for detailed information on the layout
and formatting for function headers. The following shows examples for
commented source code, and how the comments should be laid out:

void myFunc( void )
{
    int x1 = 10;    // Comment describing X1's purpose if necessary

    // Open up the file and write the value X1 to it
    ...

    /* Now do some stuff that is complicated, so we have a large block
     * comment that spans multiple lines. These should be formatted as
     * follows for C and C++ code.
     */
    ...

    // One line comments should be like this
    ...

    // C++ style multi line comments style are also allowed, but be
    // warned that not all C compilers may accept them; this could be
    // an issue when porting Open Watcom to new platforms.
    ...
}

C Header File Formatting
------------------------

This section describes the conventions used for formatting C header
files, and the conventions that you should follow if you modify or
extend any of the source code. All C header files should be contained in
a text file with the .h extension. Note that automatically generated
header files usually use a .gh extension, but those files are naturally
not intended to be edited directly.

Header File Layout
------------------

The overall layout for header files is important to help developers
quickly find their way around unfamiliar source code for the first time.
All C header files should be formatted in the following manner:

------------------------------------------------------------------------------
/****************************************************************************
*
*                            Open Watcom Project
*
*    Portions Copyright (c) 1983-2002 Sybase, Inc. All Rights Reserved.
*
*  ========================================================================
*
*    This file contains Original Code and/or Modifications of Original
*    Code as defined in and that are subject to the Sybase Open Watcom
*    Public License version 1.0 (the 'License'). You may not use this file
*    except in compliance with the License. BY USING THIS FILE YOU AGREE TO
*    ALL TERMS AND CONDITIONS OF THE LICENSE. A copy of the License is
*    provided with the Original Code and Modifications, and is also
*    available at www.sybase.com/developer/opensource.
*
*    The Original Code and all software distributed under the License are
*    distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
*    EXPRESS OR IMPLIED, AND SYBASE AND ALL CONTRIBUTORS HEREBY DISCLAIM
*    ALL SUCH WARRANTIES, INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF
*    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR
*    NON-INFRINGEMENT. Please see the License for the specific language
*    governing rights and limitations under the License.
*
*  ========================================================================
*
* Description:  Description of the header file. This should describe the
*               purpose of this header file.
*
****************************************************************************/


#ifndef _HEADER_H_INCLUDED  /* Include guard. The #define name should be   */
#define _HEADER_H_INCLUDED  /* the same as the header (ie: header.h here). */
/* HEADER_H_INCLUDED would be in the user's "namespace". Implementation headers
 * for end-user have to use names in the implementation "namespace".
 * e.g.
 * #ifndef _STDLIB_H_INCLUDED
 * #define _STDLIB_H_INCLUDED
 * ...
 * #endif
 * Only system headers (ie. headers not intended to be built with any other
 * compiler) should use reserved names.
 */

#include <stdio.h>      /* Include any dependent include files */

/* If necessary, declare structure packing; The __Packed keyword may be
 * used on individual basis instead of the #pragma.
 */
#pragma pack( push, 1 )

/* Macros, enumerations, type definitions, structures and unions should be
 * defined in this section for both C and C++ code.
 */

/* Restore the previous packing value if it has been changed */
#pragma pack( pop )

/* The following is not stricly required for header files that are not
 * intended to be included from C++ code.
 */
#ifdef  __cplusplus
extern "C" {            /* Use "C" linkage when in C++ mode */
#endif

/* Include C function prototypes in here */

#ifdef  __cplusplus
}                       /* End of "C" linkage for C++ */
#endif

#endif  /* _HEADER_H_INCLUDED */
------------------------------------------------------------------------------

Structure packing warrants further note. For structures that are only used
internally within a single project, it is highly recommended that compiler
default packing is used. This is especially important on platforms where
misaligned accesses incur significant penalties (that includes nearly all
modern processor architectures).

However, for structures that are shared by multiple projects, especially
structures that describe external data stored in files, received over
network links etc., packing is *critical*. In ideal case, structures are
designed to be naturally aligned and structure packing becomes irrelevant.
In reality, many structures aren't naturally aligned and proper packing
must be specified. Problems caused by improper structure packing are
notoriously difficult to diagnose and correct.

Enumerations
------------

Enumerations should be defined for all numerical constants used in
header files, rather than using a macro #define or a set of constants.
The reason for this is that it provides a logical grouping for related
constants, and perhaps more importantly, eases debugging (because the
debugger knows about enums but doesn't know about macros). The format