|
Christensen C Programming Style Guidelines
|
This page describes C programming style guidelines for students
of Dr. Christensen.
Programming style guidelines serve to make programs easier for a human to
read and understand. A human readable and understandable program is the
first and necessary step to reducing the number of programming errors (bugs).
My style guidelines are a mixture of influences. They may be a bit pedantic
in some places, but better to be overly clear than the opposite.
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 and note in inline comments). Files are to be .c
and not .cpp. The standard compiler that I use is Borland's free bcc32
command line compiler. Any debates on what is ANSI C will be settled with this
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 files
All program files must be stored in a single directory and listed in a
readme.txt file. Each file in the directory must be described in the
readme.txt file. File names should be reasonably short (8.3 if
possible) and certainly should not contain spaces or unusual characters.
Program headers
All programs must have a header that contains file name, short program
description, notes, example execution, execution instructions, build instructions,
known bugs, contact information, and history. All headers must conform as much
as possible 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 =
//= --------------------------------------------------------------- =
//=-------------------------------------------------------------------------=
//= Bugs: None known =
//=-------------------------------------------------------------------------=
//= Build: bcc32 summary1.c =
//=-------------------------------------------------------------------------=
//= Execute: summary1 < in.dat =
//=-------------------------------------------------------------------------=
//= Author: Ken. 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
Functions follow the main program. 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 closely to this example:
//===========================================================================
//= Function to load X array from stdin and determine N =
//=-------------------------------------------------------------------------=
//= Inputs: None (uses global X and N) =
//= 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 must have a one line (not more) header comment. Something like
this is what you should strive for:
// Compute mean, variance, standard deviation, and cov
mean = mom1;
var = mom2 - pow(mom1, 2.0);
stddev = sqrt(var);
cov = sqrt(var) / mom1;
// Output the computed summary statistics
printf(" Total of %d values \n", N);
printf(" Minimum = %f (position = %d) \n", min, minpos);
printf(" Maximum = %f (position = %d) \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 should be of modest length (generally 12 letters or less) and
should be descriptive. Local variables are all lower case, global variables
start with a capital letter. A good notation style is the so-called "camel"
notation (use of capital letters within a name). Constants are all capitals.
Do not use the letters 'O' and 'l' as variables names as they can be confused
with the numbers zero and one. All variables and constants are defined one
per line and must be commented (as shown in the above example). Examples of
a contant, global varaible, and local variable are:
#define MAX_FILES 100 // Maximum number of files
int ErrorCount; // Global count of errors
int errorCount; // Count of errors
Naming of functions
Function names should also be of modest length and should be descriptive of
the purpose or returned value of the function.
Bracket and indent style
The opening bracket must be directly below the associated statement. All
indents are two spaces. Use sum = sum + rather than the shortcut
sum += . Note also the spacing between operators. An 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 an excessive number 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 TWO 2 is silly).
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 then be described in the
program header.
Do not have commented-out debug code
Do not litter your code with commented-out debug code statements. Remove all
debug code or, at the very least, use conditional compile statement (e.g.,
#ifdef, to identify debug code statements.
Tabs are evil
Different editors display tabs differently. Avoid tabs (or, configure your
editor to convert tabs to spaces).
Illegal copying is worse than evil
If you have copied code from a legal (open source) source, then this copied
code must clearly be identified as such. In addition, any required statements
(e.g., copyleft agreement statements) from the copied code must be correctly
included.
|
Last update on June 29, 2007
|