|
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 update on August 5, 2004
|