Coding Style Guide

1) Text Basics

Files are text with 8 character tab stops (the default). Do not use line drawing or other high bit characters in a file. Files must not contain the null ('\0') character.

Standard files names:

.c
C Source code
.h
C header file
.cpp
C++ Source code
.mak
Visual C++ Makefile
Makefile
UNIX makefile.
 

2) Indentation

The standard indentation size is 4 spaces per level.

3) Curly braces

Curly braces are to be put on lines by themselves. The block enclosed by the braces is indented one level.

if (value == key)
{
    printf("Key set\n");
}
else
{
    printf("Key not set\n");
}

4) Complexity

Files should not contain more than about 2,000 to 3,000 lines of code.

About the time you start running into the right margin, you could consider rewriting your code to use procedures to reduce the number of nested curly braces.

Functions should be about 1-3 pages long. Longer functions are allowed only if the logic in the function is minimal.

No more than 10-20 lines of code should be written without a comment or blank line breaking up the block of code.

5) Variable and Constant Declarations

Naming convention:

Abbreviations should not be used whenever possible. For example, spell the word point as "point". Do not use "pt", "pnt", "pint" or any other abbreviation. This is because of the tremendous number of errors that occur when programmers abberviate things differently. Also remember that code is now internaltional and non-standard abbreviations won't show up in a English-Finnish dictionary.

6) Avoiding the "int" declaration.

The int type is not to be used. Instead use the standard names int8, int16, int32, uint8, uint16, uint32.

7) Standard Prefixes and Suffixes

The following is a universal list of prefixes and suffixes that may be used for variables and types:

_ptr
Pointer
_p
Pointer. (_ptr is preferred)
n_
Number of. (n_Entries).
_msg
Message
_MAX
Maximum. (Use as a suffix only, do not use as a prefix).
_MIN
Minimum. (Use as a suffix only, do not use as a prefix.)
v_
Variable. (i.e. "Variable shift" is "v_shift". Variable width is "v_width". Do not use this to tell me that the variable is a variable.)

8) Illegal variables

The following should never be used as a variable or contestant name:

O
Upper case "O".
l
Lower case "L".

These names are easily confused with the numbers "0" and "l".

9) Variable Declarations

Variable names consist of three parts:

type    name;    /* comment explaining the variable */

The third part is not optional.

Units should be include in the description if applicable.

10) Side effects

Avoid side effects. Specifically, put ++ and -- on lines by themselves. Also do not embed an assignment statement inside an if or other statement.

i = ++j; /* Wrong */

++j;

i = j;      /* Right */


if ((ch = getchar()) == EOF)  /* Wrong */


ch = getchar();
if (ch == EOF)   /* Right */

Note: It is a good idea to get into the habit of using "++x" instead of "x++". In C++ when you are overloading operators, "++x" is more efficient that "x++".

11) Functions

All functions not used outside the file must be declared static.

All public functions must have a prototype defined in a header file. The header file must save the same name (different extension) as the file name.

Modules must include the header that defines the prototypes for all the functions in that module.

The return value for a function should always be declared. Never let it default to int.

12) Switches

Each case in a switch statement should end in either break or /* Fall through */.

All switch statements should have a default case, even it is only /* Do nothing */.

switch (flag) 
{
    case START:
        printf("Starting\n");
        do_start();
        /* Fall through */
    case RUN:
        printf("Running\n");
        do_run();
        break;
    /* Note: The default does *NOT* have to be the last case */
    default:
        /* Do nothing */
        break;
}

13) #define

Avoiding using #define if possible. Use const declarations, typedef, or inline functions instead.

const int WIDTH = 20 + 80;   /* Good */
....
    int area = WIDTH * 5;    /* Works */
/* --------------------------------------- */

    #define WIDTH 20 + 80        /* ERROR: Should not use #define */
                                 /* ERROR: No () around definition */

....
    int area = WIDTH * 5;    /* ERROR: Assign area = 20 + 80 * 5 */
                             /* or 420, not 500 */

/* ======================================= */

#define char_ptr char *      /* ERROR: Should use typedef */
....
    char_ptr var1, var2;     /* What type is var2? */
/* Answer: It's a "char", not a "char *" */

/* Our expanded declaration looks like: */
    char *var1, var2;

/*From this you can see why "var2" is a "char" */
/* --------------------------------------- */

/* Better */
typedef char * char_ptr;   /* Define a type for strings */
....
    char_ptr var1, var2;   /* This works */

When defining a multi-line #define put all the backslashes (\) in the same column.

#define A_MACRO (A_VERY_LONG_VARIABLE_NAME +    \
                 ANOTHER_LONG_NAME +            \
                 YET_ANOTHER_LONG_NAME_TOO +    \
                 JUST_ONE_MORE_LINE)
  

References

C Elements of Style by Steve Oualline (http://www.oualline.com)