cstyle.txt

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

for defining an enumeration is as follows:

typedef enum {
    CHANGE_NORMAL   = 0x00,
    CHANGE_ALL      = 0x01,
    CHANGE_GEN      = 0x02,
    CHANGE_CHECK    = 0x04
} change_type;

Structures and Unions
---------------------

It is preferred to declare structures and unions using a typedef, so that
the structure can be used without requiring the 'struct' or 'union' keyword.
For example:

typedef struct {
    ...
} score_reg;

typedef union {
    ...
} symbol;

rather than:

struct score_reg {
};

union symbol {
};

For C++ code however, you should declare structures and unions without
using the typedef keyword, since the language treats these language
constructs differently.

Function Prototypes
-------------------

All public functions must be declared in only one header file, in the
'function prototypes' section of the header file. For C callable
functions (even if implemented in C++) the function prototypes must be
bracketed with the extern "C" statement as shown in the sample header
file above. This is to ensure that all global functions will be callable
from both C and C++ code. Each public function should be declared on a
single line. The function prototype should also be indented so that the
function modifier value (MYAPI in this case) is lined up for all
functions, inserting as many necessary spaces to get all functions to
align.

Although it may seem strange to format functions prototypes in this
manner, the C/C++ compiler will do the necessary job of checking that
the parameters in the prototype are correct with respect to the function
body, and having a single function per line makes it easy to browse
header files to find a specific function prototype. Note also that this
is one case where you must violate the 80 characters per line guideline
and not break the function prototype across multiple lines, no matter
how many parameters it takes. For instance a couple of prototypes might
be implemented as follows:

bool          MYAPI my_function( int arg1, int arg2 );
my_structure *MYAPI my_function2( int arg1, int arg2, int arg3 );

Global Variables
----------------

Any public global variables must be declared in the header file in the
'global variables' section. When formatting global variables
declarations, format them so that the names of the variables align on
"tab stops". For example:

// 45678 1 2345678 2 2345678
extern int          my_var1;
extern ulong        my_var2;
extern score_reg    my_structure;
extern long         *my_pointer;

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 .hpp extension. Where a header file is designed
to be used for both C and C++, it should end in a .h extension and
include C++ specific definitions with a #ifdef cplusplus conditional
compilation block.

For the most part formatting and documentation of enumerations,
structures, unions, function prototypes and external variables is
identical to C header files, so refer to the sections above for
information on this.

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_HPP        // Mandatory include guard. The #define name must
#define HEADER_HPP        // be the same as the header (ie: header.hpp here).
                          // Implementation reserved names (prefixed with
                          // an underscore) should be used where appropriate.

#include <iostream>       // Include any dependant include files


// If necessary, declare structure packing; The __Packed keyword may be
// used on individual basis instead of the #pragma.
// See C header description for additional information on structure packing.
#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 )

// Any C++ class definitions should be defined in this section.

// Any large C++ inline member functions that are not defined in the
// class definition itself should be defined in this section.

// Include C++ only callable function prototypes in here

#ifdef  __cplusplus
extern "C" {            // Use "C" linkage when in C++ mode
#endif

// Include C callable function prototypes in here. If none of the functions
// are callable from C, this section can be removed (with the extern "C"
// sections).

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

#endif  // __HEADER_HPP
------------------------------------------------------------------------------

C++ Class Definitions
---------------------

When declaring C++ classes, you should structure them with the private
and protected variable definitions first, following by protected
functions and then public functions. By declaring things in this order
you can immediately use variables in inline functions in the class
definition [can't you do so even with the private section at the
bottom?]. You should also indent the member function declarations by
three indentation levels (12 spaces) in order to leave room for the
'virtual', 'static' and 'friend' modifiers. This way all the function
declarations line up neatly within the class. Please document each
member function of the class unless it is entirely obvious what the
member is intended to do, by placing a C++ style comment (//) on the
line before the member function declaration, and with an indentation of
three levels (to line up with the start of the function declaration).
Also please provide a small descriptive comment for all member variables
describing the purpose of the variable. For small inline functions,
place the function body within the class declaration. For inline
functions that are more than about 2 lines long, please place the body
of the function after the class definition in the same header file.

Generally try to place a single class definition into a single header
file, however it may be more convenient in some instances to place
multiple class definitions into a single header file (for small,
logically related classes such as a node class and the list class that
uses the nodes).

The following is a template for how a C++ class definition should be
formatted:

class MyClass {
protected:
    int myVar;              // Describe what this is for

            // Comment for the function
    virtual void myProtectedFunction();

public:
            // Constructor
            MyClass();

            // Destructor
            ~MyClass();

            // Always document virtual functions
    virtual void myPublicVirtual();
    friend  void myPublicFriend();

            // How to format inline functions...
    inline  void smallInlineFunction() { // function body; };

    inline void mediumInlineFunction()
            { // function body; };

    inline  void largeInlineFunction()
            {
                // First line of function
                // Second line of function
            };

    inline  void reallLargeInlineFunction();
    };

C++ Inline Member Functions
---------------------------

For C++ classes that have inline member functions that are larger than
will easily fit within the class definition (ie: more than say 2 lines
of code), they should be declared separately in the 'inline member
functions' section of the header file. A typical declaration would be as
follows:

inline void MyClass::reallyLargeInlineFunction()
{
    // function body
}

C++ Template Definitions
------------------------

The parameter list for a template should be formatted, if possible,
entirely on a single line. It is recommended that a space be placed
immediately after the opening '<' and immediately before the closing
'>'. This makes it less likely that the unexpected tokens will be
produced (particularly '>>' or '<:'). It is also consistent with the way
functions are formatted according to this guide. For example:

template< class T, class U >
class MyClass {
    ...
};

template< class T >
void f(
    const T &x,
    const T &y )
{
    ...
}

In cases where the template parameter list is very long the parameters
can be provided each on lines by themselves in a manner similar to the
way function parameter lists are formatted. For example:

template<
    class CharT,
    class Traits = char_traits< CharT >,
    class Allocator = allocator< CharT > >
class basic_string {
};

This format is less desirable in general because in the case of a
function template, it can produce a confusing list of different kinds of
parameters. For example:

template<
    class CharT,
    class Traits,
    class Allocator >
basic_string< CharT, Traits, Allocator >::basic_string(
    const basic_string &other,
    size_type  pos,
    size_type  n,
    const Allocator &a ) : mem( a )
{
    ...
}

The above function is more appropriately formatted as:

template< class CharT, class Traits, class Allocator >
basic_string< CharT, Traits, Allocator >::basic_string(
    const basic_string &other,
    size_type  pos,
    size_type  n,
    const Allocator &a ) : mem( a )
{
    ...
}

In general the formatting of member functions of templates is difficult
because of the complex syntax C++ requires. Every reasonable attempt
should be made to keep lines shorter than 80 characters. This may
require taking liberties with the usual formatting rules. For example:

template< class CharT, class Traits, class Allocator >
inline
basic_string< CharT, Traits, Allocator >::iterator
    basic_string< CharT, Traits, Allocator >::begin( )
{
    ...
}

In the example above the return type, due to its great length, is
formatted on a line by itself. The 'inline' specifier is also provided
on a line by itself to help keep it from being lost. Finally the name of
the function is indented to visually separate it from the name of the
return type.


NOTE: At this stage the format for documenting C++ classes and member
functions is not completed finished, so the above will likely change
when the documentation system for C++ classes is finalised.