1. C Source file format

The following defines the common C source file format for linux-wlan. Most of the C-code formatting rules come from the linux kernel document CodingStyle.

2. Characters and Code layout

2.1. Character Set

For all source files, we'll stick to the US character set and avoid all trigraphs.

2.2. Indentation

All indentation will be done using tab characters which are mapped to a spacing of eight characters.

2.3. Braces

Braces will be placed according to the format originally established in Kernighan and Ritchie's book "The C Programming Language". Here are some example statements:

for ( i= 0; i < N; i++) { . . . } if ( a < b ) { . . . } else { . . . } do { . . . } while ( i >> 0 );

3. Naming and Definition Conventions

3.1. Preprocessor Elements

All elements defined via the C preprocessor (constants and macros) are named using all capital letters. An exception is for macros that are either wrapping function calls for portability or for macros that are inline replacements for code that would normally be in a function.

3.2. Types

All programmer defined types must have single word type names defined using the

typedef

statement. All type names should be identified with an

_t

suffix. This is particularly important for function pointers that are members of structures or arguments to functions.

Anonymous types are not allowed. All struct, union, and enum types shall be named and typedef'd.

3.3. Variables

The following conventions should be followed for variable declaration and naming:

Variables should be named using meaningful names.
Avoid variables with static lifetimes.
If static lifetime variables must be used, use file scoped static variables and avoid static lifetime variables with visibility beyond file scope.
All static lifetime variables should be declared in the "Local Statics" section near the top of a given source file.

3.4. Functions

The following conventions should be followed for function declaration and definition:

All functions must be declared above the point where they are called.
Any functions that are only intended to be called within a given source file should be declared static within that file.
Functions defined within a common source file that are visible across source file boundaries should be named using a prefix that is unique to that source file.

4. File Layout

Each file should be layed out using a common format. The following shows a complete file with all its major sections.

Each major section within the file is begun with a comment of the form:

/*================================================================*/
/* [Section Name] */

Subsections within a major section are denoted using:

/*----------------------------------------------------------------*/
/*  [Subsection Name]  */

/* [filename]: [one line description of the file] * -------------------------------------------------------------------- * * [Project Name] * * [License Statement] * * [Warranty Statement] * * [Initial Author Statement] * * -------------------------------------------------------------------- * * [Initial Author Contact] * * -------------------------------------------------------------------- * * [File Description] * * [Implementation and Usage Notes] * * -------------------------------------------------------------------- */ /*================================================================*/ /* System Includes */ /*================================================================*/ /* Project Includes */ /*================================================================*/ /* Local Constants */ /*================================================================*/ /* Local Macros */ /*----------------------------------------------------------------*/ /* [A subsection] */ /*================================================================*/ /* Local Types */ /*================================================================*/ /* Local Static Definitions */ /*================================================================*/ /* Local Function Declarations */ /*================================================================*/ /* Function Definitions */

4.1. System Includes Section

Preprocessor #include statements that are including system includes shall be placed in this section. System includes are those include files that are not part of the managed source for this project.

4.2. Project Includes Section

Preprocessor #include statements that are including project includes shall be placed in this section. Project includes are those include files that are a part of the managed source for this project.

4.3. Local Constants Section

Preprocessor "manifest" constants that are local to this file shall be placed in this section. "Manifest" constants are preprocessor macros that take no arguments.

4.4. Local Macros Section

Proprocessor macros that accept arguments shall be placed in this section.

4.5. Local Types Section

Programmer defined types that are only used within the scope of this file shall be defined in this section. Programmer defined types that are used in more than one source file should be defined in a header file.

4.6. Local Static Definitions Section

Variables with static extent that are defined within this file shall be placed in this section. Whether a variable has scope beyond this file will be apparent based on the presence or absence of the static keyword in the declaration. If a variable is declared without the static keyword, there should be an extern declaration for that variable in a header file.

4.6. Local Function Declarations Section

Functions that are only used within this file should be declared (prototyped) in this section. Additionally, these functions should be declared using the static keyword. This avoids polluting the global namespace with function names that need not be extern.

Any functions defined in this file that are called from outside this file should be declared (prototyped) in a header file.

4.6. Function Definitions Section

This section contains the definitions of the functions in this file. Each function (or group of strongly related functions) will be preceded by a function header comment (see below).

5. Comments

5.1. File Header

Each source file will have a header comment containing information about the file as a whole. That comment shall be formatted:

5.2. Function Header

Each function (or group of closely related functions) will be preceded by a function comment header. The Side effects and Call context sections are optional.

/*---------------------------------------------------------------- * [function name] * * [description] * * Arguments: * [argument list] * * Returns: * [return value list] * * Side effects: * [description of function side effects] * * Call context: * [description of calling context] ----------------------------------------------------------------*/