| 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 noted in inline comments). Files are to be .c and not .cpp.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 must not contain spaces or unusual characters.Program headers
All programs must have a header that contains the 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 a 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: gcc summary1.c -o summary1 = //=-------------------------------------------------------------------------= //= Execute: summary1 < in.dat = //=-------------------------------------------------------------------------= //= Author: Ken Christensen = //= University of South Florida = //= WWW: http://www.cse.usf.edu/~christen = //= Email: christen@cse.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 (size of array) = //=-------------------------------------------------------------------------= //= Inputs: None (uses global variables X and N) = //= Returns: X and N (global variabels) = //=========================================================================== void load_X_array()
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 below example). Examples of a constant, global variable, and local variable are (note that global variable names start with a capital letter and local variable names with a lowercase letter):#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
// 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 or screen (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 - this is easily done in most editors).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.
|
|