CSC 101 Programming Conventions, Volume 1

Introduction

This handout presents conventions that must be observed by all CSC 101 programmers. 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. 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.

////
//
// Program description goes here ... .
//
// Author: first and last name (email address)
// Created:  date in the form ddmmmyy, e.g., 30mar99
// 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 five integers entered from the
// terminal.  The statistics computed are the sum of the numbers, the
// arithmetic mean, and the standard deviation.  The computed results are
// output to the terminal.  Note that since all numbers are computed with
// integer arithmetic, the mean and standard deviation are truncated to the
// nearest integer value.
//
// Author: Gene Fisher (gfisher@calpoly.edu)
// Created: 30mar99
// Last Modified: 2apr99
//
////

Program Variable Names

Program variable names must be comprised of all lowercase letters ¹ 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:

    int i1, i2, i3, i4, i5;             // Input variables
    int sum;                            // Computed sum
    int mean;                           // Computed mean
    int 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.
    //
    cout << "Enter five integers, separated by spaces: ";

    //
    // Input the numbers.
    //
    cin >> i1 >> i2 >> i3 >> i4 >> i5;

    //
    // Compute the sum.
    //
    sum = i1 + i2 + i3 + i4 + i5;

    //
    // 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:

    int i1, i2, i3, i4, i5;
    cout << "Enter five integers, separated by spaces: ";
    cin >> i1 >> i2 >> i3 >> i4 >> i5;
    sum = i1 + i2 + i3 + i4 + i5;
    mean = sum / NUM_DATA_POINTS;

    int i1,i2,i3,i4,i5;
    cout<<    "Enter five integers, separated by spaces: ";
    cin>>i1>>i2>>i3>>i4>>i5;
    sum=i1+i2+i3+i4+i5;
    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.

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) +
                    pow(i4 - mean, 2) +
                    pow(i5 - mean, 2)) / (NUM_DATA_POINTS - 1));

    //
    // Output the results.
    //
    cout << endl
         << "Sum = " << sum << ", "
         << "Mean = " << mean << ", "
         << "Standard deviation = " << std_dev << ", "
         << endl << endl;

Footnotes

¹ The convention of all lowercase letters in variable names is one of a few places where Fisher's conventions are different than the textbook.