CSC 101 Programming Conventions, Volume 1

Introduction

This handout presents conventions that must be observed by all CSC 101 programmers in Gene Fisher's section of the class. These conventions are the first in a series that will describe precisely the programming standards for CSC 101. This first volume of conventions covers the C features that will be used in Programming Assignment 1 and Programming Assignment 2. As additional C language features are presented in class, there will be additional conventions to cover the new features.

Top-Level Program Documentation

All programs must begin with an explanatory comment at the top of the program file. The comment describes in high-level terms what the program does, including inputs it takes in and outputs it produces. If there are any noteworthy conditions that should be understood by the program user, these conditions should be explained as well. Following the descriptive comments are three additional lines that identify the program author, the date the program was initially created, and the date the program was last modified.

The explanatory comment must be formatted precisely as follows:

/****
*
* Program description goes here ... .
*
* Author: first and last name (email address)
* Created: date in the form ddmmmyy, e.g., 30mar11
* Modified: date in the for ddmmmyy
*
*/

The following is an example of a conventionally correct explanatory comment (this example is taken from the sample program in Lecture Notes Week 2

/****
 *
 * This program computes simple statistics for three real numbers read from
 * standard input.  The statistics computed are the sum of the numbers, the
 * arithmetic mean, and the standard deviation.  The results are output to
 * standard output, in the following form:
 *
 * Sum =
 * Mean =
 * Standard Deviation =
 *
 * The precise formulae for mean and standard deviation are as defined here:
 *
 *    http://www.gcseguide.co.uk/statistics_and_probability.htm
 *
 *
 * Author: Gene Fisher (gfisher@calpoly.edu)
 * Created: 31mar11
 * Last Modified: 4apr11
 *
 */

Program Variable Names

Program variable names must be comprised of all lowercase letters, digits, and possibly underscore characters. For variable names that are more than one word, each word is separated by an underscore. Underscore characters are used only as word separators, so variables must not begin or end with an underscore. The following are examples of conventionally correct variable names:

i1
i2
sum
mean
std_dev
employee_pay_rate

I1
I2
Sum
MEAN
stdDev
Employee_Pay_Rate

Variable names must be sufficiently mnemonic to convey their usage in the program in which they appear. Typically, this means that a variable name is one or more descriptive English words or abbreviated words. Occasionally, very short variable names are satisfactory. For example, in a program where a single integer variable is used as an input, the variable can be named simply "i". Note well that a short variable name is only acceptable when the name is completely adequate to convey its use. Typically, programs are more understandable when full English words or clear abbreviations are used to name variables.

Program Constant Names

Program constants must be comprised of all uppercase letters and possibly underscore characters. For constant names that are more than one word, each word is separated by an underscore. Underscore characters are used only as word separators, so constants must not begin or end with an underscore. The following are examples of conventionally correct constant names:

LIMIT
MAX_INPUT
NUM_DATA_POINTS

In-Line Documentary Comments

Each variable declaration must be followed by a brief comment that describes what the variable is used for. If two or more variables of similar use are declared together, all these variables may be described with one comment. The following are examples of conventionally correct variable declarations:

    double x1, x2, x3, x4, x5;          /* Input variables */
    double sum;                         /* Computed sum */
    double mean;                        /* Computed mean */
    double std_dev;                     /* Computed standard deviation */

Within the body of a program, sequences of one or more logically-related statements must be preceded with a comment that describes in English what the statements do. These comments document the higher-level algorithm that the C program statements implement. A very effective way to develop programs is to write the algorithm comments first, and then fill in the code details.

The following are examples of conventionally correct in-line code comments:

    /*
     * Prompt the user for the input.
     */
    printf("Enter five real numbers, separated by spaces: ");

    /*
     * Input the numbers.
     */
    scanf("%lf%lf%lf%lf%lf", &x1, &x2, &x3, &x4, &x5);

    /*
     * Compute the sum.
     */
    sum = x1 + x2 + x3 + x4 + x5;

    /*
     * Compute the mean.
     */
    mean = sum / NUM_DATA_POINTS;

1. be indented to the same column as the statement(s) it precedes

2. start with a completely blank line, followed by a line containing only the two comment characters "/*"

3. follow with one or more comment lines, written in complete English sentences

4. end with a line containing only the two comment characters "*/"

Program Spacing and Indentation

All comma-separated lists must have a space following each comma. All arithmetic, input, and output operators must be separated by one space from their operands. The following are examples of conventionally correct indentation and spacing:

    double x1, x2, x3, x4, x5;
    scanf("%lf%lf%lf%lf%lf", &x1, &x2, &x3, &x4, &x5);
    sum = x1 + x2 + x3 + x4 + x5;
    mean = sum / NUM_DATA_POINTS;

    double x1,x2,x3,x4,x5;
    scanf("%lf%lf%lf%lf%lf",&x1,&x2,&x3,&x4,&x5);
    sum=x1+x2+x3+x4+x5;
    mean=sum/NUM_DATA_POINTS;

Each single-line statement within a function must be indented exactly four spaces. The indentation must be typed as four separate space characters, NOT as a tab character, even if you use an editor that allows you to set the width of a tab to four spaces. If tab characters are used for indentation, they always count as eight spaces. The best thing to do is use NO TABS AT ALL, in a program, indenting with space characters only, in multiples of 4.

Long statements may be separated onto multiple lines for improved readability. In such cases, lines after the first are indented to a visibly appropriate column. The following are examples of multi-line statements where the lines after the first are further indented for readability:

    /*
     * Compute the standard deviation.
     */
    std_dev = sqrt((pow(i1 - mean, 2) +
                    pow(i2 - mean, 2) +
                    pow(i3 - mean, 2)) / (NUM_DATA_POINTS - 1));

    /*
     * Output the results.
     */
    printf("Sum = %f0, sum);
    printf("Mean = %f0, mean);
    printf("Standard Deviation = %f0, std_dev);

Function Declarations and Definitions

Functions must be declared and defined in two parts:

1. Function prototypes, i.e., the declarations at the beginning of the program.

2. Function definitions below, where they most meaningfully fit in the program.

/*
 * Function prototypes.
 */

Each function definition requires a comment that describes what the function does, in terms of the value it returns with the inputs it is given. The comment is in one or more English sentences, using the word "return" for the computed value, and word "given" for the input parameters. Include an input/output example of what the function does, if this is helpful in understanding it.

Here are two example function comments from the assignment write ups and lecture notes:

/*
 * Return the sum of the given three numbers.
 */
double compute_sum(double x1, double x2, double x3) {
    return x1 + x2 + x3;
}


/**
 * Return the correct number of dollars in change for the given amount of
 * cents.  For example, if cents = 284, get_dollars returns 2.
 */
int get_dollars(int cents) {
    return cents / 100;
}

Function Size Limits

No function, including main, may be longer than 50 lines. The 50-line length does not include comments or blank lines. This rule may not be achieved by condensing lines in such a way as to violate any of the preceding formatting conventions.

As we learn more features of C, the formatting rules for what constitutes a "line" will become more fully defined. In the meantime, that is for programs 1 and 2, follow the preceding formatting conventions. A line is any non-comment, non-whitespace program line, which must be less than or equal to 80 characters in length.

Scoring

Scoring of 101 programs is based on execution results and adherence to coding conventions. Points for program execution are defined in the test drivers for each program, on a 100-point scale.

After the execution score is determined for a program, points are deducted for any violations of the conventions specified in this handout. The following are the specific deductions:

• -8 points for each uncommented program file, up to a total of -16 points
• -2 points for missing Author
• -1 points for missing Created date
• -1 points for missing Modified date
• -4 points for each uncommented function, up to a total of -16 points
• -3 points for each function longer than 50 lines, up to a total of -12 points
• -2 point for each uncommented local variable, up to a total of -8 points
• -2 points for each egregious violation of any other coding convention defined above, up to total of of -8 points.