cstyle.txt

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

Open Watcom C/C++ Source Code Style Guidelines

Contents
 1  Introduction
 2  Indentation and Tab Width
 3  Source Code Width
 4  C/C++ Source Code Formatting
 4  Source File Layout
 4  Function Body
 7  Flow Control Statements
 7  If-Else Statements
 8  While Statements
 8  Do While Statements
 8  For Statements
 8  Switch Statements
 9  Expressions
 9  Variable Declarations
 9  Global Variables Within a Module
10  Comments and Commenting Style
11  C Header File Formatting
11  Header File Layout
12  Enumerations
13  Structures and Unions
13  Function Prototypes
14  Global Variables
15  C++ Header File Formatting
15  Header File Layout
16  C++ Class Definitions
18  C++ Inline Member Functions
19  C++ Template Definitions

Introduction
------------

Open Watcom products are usually written in C, C++ and assembler. This
document describes the style conventions used by Open Watcom
contributors for all Open Watcom projects, and is intended to be used as
a guideline if you are going to be modifying the source code in any way.
Any contributed code that is to be included in a Open Watcom product
must follows these style guidelines, and submissions violating these
guidelines will be rejected. By following these style guidelines, all
the source code for Open Watcom products will be in a consistent format,
which will ease the burden of finding one's way around the source code.

It is important to have all source code formatted in a similar manner as
this helps to give the entire product a cohesive image, and makes
finding your way around the source code much easier. Because C and C++
are entirely free-form, there are many different ways that the source
code can be formatted. All programmers have their own preferred
formatting style, just as all writers have their own personal writing
style. However just as when multiple authors work on a single book,
multiple programmers working on a common software product should adhere
to consistent formatting and style conventions.

This document is intended to serve as a guide to the style guidelines
used by Open Watcom developers. If, however, something is not clearly
documented here, the best reference to the style guidelines is to look
at some Open Watcom source code.

NB: The Open Watcom source code is very large (over two million lines of
C/C++ source code) and was written by many people over the period of
almost 20 years. As a result, not every source file conforms to these
guidelines. You may wish to reformat existing non-conforming source
files, but if you do so, please observe the following. It is highly
recommended that you reformat an entire project or subproject instead of
a single source file, and never mix formatting changes with functional
changes. Always submit formating changes separately, as it makes source
code maintenance much easier.

Indentation and Tab Width
-------------------------

All source code should be formatted to use 4 space tabs, and all
indentation should be in multiples of 4 spaces (one indentation level).
The source code should be formatted using only real spaces and never
hard tabs, so you will need to configure your editor to use 4 space tabs
and to insert spaces only into the source code. Do NOT use 8 space hard
tabs in your source code! If you absolutely must work with 8 space hard
tabs, please run the resulting source code through a tab expansion
utility. Note that this also includes assembly code!

Source Code Width
-----------------

All source code should try to use a maximum of 80 characters per line.
Some editors can only display 80 characters on a line, and using more
can cause them to exhibit line wrap. This is only a guideline, and if
more than 80 characters will enhance the legibility of the code, use
wider source lines---but not too much wider.

C/C++ Source Code Formatting
----------------------------

This section describes the conventions used for formatting C and C++
source code modules, and the conventions that you should follow if you
modify or extend any of the source code. All C source code should be
contained in text files with the .c extension, and all C++ source code
should be contained in text files with the .cpp extension. It is highly
recommended that all source file names are lowercase and following the
8.3 convention for maximum portability.

Source File Layout
------------------

The overall layout for source code is important to help developers
quickly find their way around unfamiliar source code for the first time.
All C and C++ source code modules 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 code module. This should describe the
*               purpose of the code in this module.
*
****************************************************************************/


#include "myhdr.h"      /* Include any necessary headers */

/* Global variable declarations and static globals local to module */

/* All functions implemented in this module. Where possible static or
 * private functions should be located before functions that use them to
 * avoid the need for superfluous function prototypes. However all functions
 * *MUST* have a prototype, so if necessary add local prototypes to the top
 * of the file before the regular functions begin.
 */

------------------------------------------------------------------------------

Function Body
-------------

The body of a C or C++ function should be written with the open brace
that starts the body of the function in the leftmost column, and the
closing brace in the same column. All source code statements contained
within the function body should start at the first indentation level (4
spaces in). The name of the function and an opening '(' should be on the
first line, with the return type preceding the function name. Between
the return type and the function name may be a macro for the function
type modifier. Using a macro for this modifier allows it to be changed
to suit new operating environments, such as __pascal or __stdcall for
Windows environments by only changing a single macro definition.

If the function is static or private, it may be left without any
preceding documenation provided the function is short. However any
function that contains more than about 5 lines of source code and all
public functions should be preceded with a source code comment. An
example of a properly formatted function with documentation header is as
follows:

// Concise description of the function.
// May use C or C++ style comments.
bool MYAPI my_function( int arg1, int arg2 )
{
    // function body goes here.
}

If a function has too many arguments to comfortably fit on a single line,
the line needs to be broken up appropriately. Recommended formatting is
as follows:

void my_long_function( first_complex_type *arg1, second_complex_type *arg2,
    int arg3, third_complex_type *arg4 )
{
    // function body goes here
}

Note that a C language function which takes no parameters should be
declared as type foo( void ) rather than type foo(). The former says foo
has no parameters; the latter that nothing is known about the
parameters.

Flow Control Statements
-----------------------

All the flow control statements should have the open brace placed on the
same line as the start of the flow control statements, and all
statements that are part of the body of the flow control statement
should be indented by one level (4 spaces). The closing brace should be
indented to be at the same level as the flow control statement keyword.
This helps to partition the statement into the declaration section and
the body section of the statement. Note also that the flow control
statements should be formatted with a single space after the open
parenthesis and before the close parenthesis and after the open brace
for legibility. For example:

if( condition ) {
}

rather than the less legible

if(condition){
}

Where the dependent statement does not require braces, it may, in order
of preference, either:

a) given braces it does not strictly need

if( condition ) {
    consequence;
}

b) or be indented on the next line

if( condition )
    consequence;

c) or be placed on the same line

if( condition ) consequence;

The last form is not recommended for practical reasons. If a conditional
statement is formated like

if( condition ) do_something();

it is not immediately obvious when stepping over the line in a debugger
whether the condition was true or false. Hence if this form is used, it
should only ever be done with control constructs such as return, break
or continue. Even so, it is impossible to put a breakpoint on the conditional
statement in a line oriented debugger, therefore this form should be avoided.

The following shows the templates to use for formatting each of the flow
control structures in C and C++.

If-else Statements
------------------

if( x < foo ) {
    // do something;
} else {
    // do something else;
}

If you wish to use multiple if-else statements strung together, do so
like this:

if( x < foo ) {
    // do something;
} else if( x < blah ) {
    // do something else;
} else {
    // default case;
}

When you have an if-else statement nested in another if-else statement,
put braces around the nested if-else. For example:

if( foo ) {
    if( bar ) {
        win();
    } else {
        lose();
    }
}

rather than the less legible:

if( foo )
    if( bar )
        win();
    else
        lose();

While Statements
----------------

while( x > 1 ) {
    // do something;
}

Do-while Statements
-------------------

do {
    // do something;
} while( x > 1 );

For Statements
--------------

for( i = 0; i < 10; i++ ) {
    // do something;
}

Note that with the for statement, there is no space before the
semi-colons, and there is always a single space after the semicolon. For
example avoid formatting your statements like this:

for(i=0;i<10;i++){
}

If you wish to include multiple definitions in the initialisation
section of the for statement, or multiple operations in the counter
section of the for statement then use the comma operator. However ensure
that a space always follows the comma:

for( i = 0, j = 0; i < 10; i++, j += 10 ) {
}

In cases where an "endless" loop is needed, the form

for( ;; ) {
    // do something;
}

should be used instead of the alternative

while( 1 ) {
    // do something in a not so nice way;
}

Switch Statements
-----------------