Christensen C Programming Style Guidelines

This page describes the C programming style guidelines for students of Dr. Christensen.

Most large and successful high-tech companies will have programming style guidelines. These style guidelines are enforced by walk-throughs and peer reviews. Over the years I have adopted my own style. If I am to review student source code, then the source code must comply to my style guidelines! Programming style is similar to spoken language, one can usually always detect what was the first learned language. As one gets older, one picks-up influences (some good and some bad) and one also "ossifies" both good and bad habits. So, here are my guidelines. You can call me archaic, but you cannot call me sloppy! The astute student will see influences from FORTRAN and Pascal (my first languages) and ideas I picked-up working at IBM. The astute student may also say "this is ridiculous, I have a better style". If so, I encourage the student to come teach me the better style! If the student really has a better style, then I will gladly adopt it.

Language and compiler

All C code is to be ANSI standard C. There shall be no use of machine or compiler specific extensions unless absolutely needed (and then thusly described in the program header). Files and to be .c and not .cpp. The standard compiler that I use is Borland's free bcc32 command line compiler.

Source code listing

All source code must be limited to 80 columns to allow for a direct (unformatted) print. Wrapped lines should be avoided as much as possible.

Program headers

All programs must have a header that contains file name, short program description, notes, example execution, execution instructions, build instructions, contact information, and history. All headers must conform exactly to this example:

//=================================================== file = summary1.c =====
//=  Program to compute summary statistics for a series X of size N         =
//=   - Computes min, max, sum, mean, var, std dev, and cov                 =
//===========================================================================
//=  Notes:                                                                 =
//=    1) Input from input file "in.dat" to stdin (see example below)       =
//=        * Comments are bounded by "&" characters at the beginning and    =
//=          end of the comment block                                       =
//=    2) Output is to stdout                                               =
//=-------------------------------------------------------------------------=
//= Example "in.dat" file:                                                  =
//=                                                                         =
//=    & Sample series of data which can be integers or reals.              =
//=      There are 11 values in this file. &                                =
//=    50                                                                   =
//=    42                                                                   =
//=    48                                                                   =
//=    61                                                                   =
//=    60                                                                   =
//=    53                                                                   =
//=    39                                                                   =
//=    54                                                                   =
//=    42                                                                   =
//=    59                                                                   =
//=    53                                                                   =
//=-------------------------------------------------------------------------=
//= Example output (for above "in.dat"):                                    =
//=                                                                         =
//=   ---------------------------------------------- summary1.c -----       =
//=     Total of 11 values                                                  =
//=       Minimum  = 39.000000 (position = 6)                               =
//=       Maximum  = 61.000000 (position = 3)                               =
//=       Sum      = 561.000000                                             =
//=       Mean     = 51.000000                                              =
//=       Variance = 52.545455                                              =
//=       Std Dev  = 7.248824                                               =
//=       CoV      = 0.142134                                               =
//=   ---------------------------------------------------------------       =
//=-------------------------------------------------------------------------=
//=  Build: bcc32 summary1.c                                                =
//=-------------------------------------------------------------------------=
//=  Execute: summary1 < in.dat                                             =
//=-------------------------------------------------------------------------=
//=  Author: Kenneth J. Christensen                                         =
//=          University of South Florida                                    =
//=          WWW: http://www.csee.usf.edu/~christen                         =
//=          Email: christen@csee.usf.edu                                   =
//=-------------------------------------------------------------------------=
//=  History: KJC (05/23/00) - Genesis                                      =
//=           KJC (06/06/02) - Changed MAX_SIZE to 2 million                =
//===========================================================================
//----- Include files -------------------------------------------------------

//----- Defines -------------------------------------------------------------

//----- Global variables ----------------------------------------------------

//----- Function prototypes -------------------------------------------------

//===== Main program ========================================================

Function headers

Each function in a program must contain a header that contains a description of the function, input variables, and output (return) variables. All function headers must conform exactly to this example:

//===========================================================================
//=  Function to load X array from stdin and determine N                    =
//=-------------------------------------------------------------------------=
//=- Inputs: None                                                          -=
//=- Returns: X and N                                                      -=
//===========================================================================
void load_X_array(void)

Inline commenting

Your source code listing must be broken-up into logical blocks of code and each block has a one line (not more) header comments. Something like this:

// Compute mean, variance, standard deviation, and cov from mom1 and mom2
mean = mom1;
var = mom2 - pow(mom1, 2.0);
stddev = sqrt(var);
cov = sqrt(var) / mom1;

// Output the computed summary statistics
printf("  Total of %ld values \n", N);
printf("    Minimum  = %f (position = %ld) \n", min, minpos);
printf("    Maximum  = %f (position = %ld) \n", max, maxpos);
printf("    Sum      = %f \n", sum);
printf("    Mean     = %f \n", mean);
printf("    Variance = %f \n", var);
printf("    Std Dev  = %f \n", stddev);
printf("    CoV      = %f \n", cov);
printf("---------------------------------------------------------------\n");

Naming of variables and constants

Variable names are of modest length (say, 12 letters or less) and are meaningful. Local variables are all lower case, global variables start with a capital letter. Constants are all capitals. All variables and constants are defined one per line and must be commented (as shown in the above example). Some examples:

#define          MAX_FILES 100 // Maximum number of files

int Error_count;               // Global count of errors

int error_count;               // Count of errors

Bracket and indent style

The opening bracket must be directly below the associated statement. All indents are two spaces. Note also that I use sum = sum + rather than the shortcut sum += . Note also the spacing between operators. Am example:

// Compute the sum and product of MAX values in X[]
for (i=0; i<MAX; i++)
{
  sum = sum + X[i];
  product = product * X[i];
}

Avoiding excessive numbers of functions

A programming style that considers 2 or 3 lines of code to be a function is unacceptable. A function should be about one page (60 lines) of code. Anything much less and it should be inline. Anything much more should be split into multiple functions. This is not a hard-and-fast rule, but a "majority of the cases" rule.

Avoid magic numbers

Your program must not contain "magic numbers". Use instead defined constants. However, do not get carried away (e.g., #define ZERO 0 is silly).

Tabs are evil

Different editors display tabs differently. Avoid tabs (or, configure your editor to convert tabs to spaces).

Compile-time warnings are not OK

There must be no compile time warnings. If a warning condition cannot be removed for some good reason, this good reason must be described in the program header.

Last updated by Ken Christensen on AUGUST 25, 2003