CSC 101 Programming Conventions, Volume 2

Introduction

This handout presents additional conventions, as a follow-on to the conventions presented in volume 1. The new conventions presented here apply to programming assignment number 6.

Program Scoping

All program variables are declared local to a function. Global variables, i.e., variables declared outside of a function, are not used.

File Naming

A multi-file program is comprised of four or more files, as follows:

1. one or more .h files containing function declarations, typedef declarations, and/or constant declarations
2. one or more .cpp files, containing function definitions for the functions declared in the .h files; specifically, for each .h file with root file name X, there is a companion file X.cpp containing a definition for each function declared in X.h
3. one or more .cpp files containing testing functions, plus a main test driver function; these files are named T-tests.cpp, for some suitably mnemonic root filename T
4. one .cpp file containing the main function for the complete program; this file is named P-main.cpp, for some suitably mnemonic root filename P

Control Construct Formatting

The following function body illustrates formatting and indentation of C++ control constructs:

ReturnType SomeFunction(ParmType_1 p1, ..., ParmType_m pm) {

    VarType_1 var1;                    // Comment ...
    ...
    VarType_n varn;                    // Comment ...

    //
    // Comment ... .
    //
    if (...) {
        ...
    }
    //
    // Comment, if necessary.
    //
    else if {
        ...
    }
    ...
    //
    // Comment, if necessary.
    //
    else {
        ...
    }

    //
    // Comment ... .
    //
    while (...) {
        ...
    }

    //
    // Comment ... .
    //
    for (...) {

        ...

    }

    //
    // Comment ... .
    //
    for (start-expression; while-expression; end-expression) {
        ...
    }

    //
    // Comment ... .
    //
    for (long-start-expression ... ;
            long-while-expression ... ;
                long-end-expression) {
        ...
    }

    //
    // Comment ... .
    //
    switch (...) {
        //
        // Comment, if necessary.
        //
        case c1:
            ...
            break;
        ...
        //
        // Comment, if necessary.
        //
        case cs:
            ...
            break;
    }
}

In general, each control construct begins with one or more lines containing the construct keyword(s), additional necessary opening syntax, and a left curly brace at the end of last (only) opening line. The statements of the construct body are indented four spaces to the right of the column in which the keyword appears. The body ends with with a right curly brace on a line of its own, indented to the same column as the beginning of the keyword.

Function Names

Function names are comprised of upper- and lowercase letters. The name begins with an uppercase letter and is followed by zero or more lowercase letters of the first word of the name. Each additional word or word abbreviation of the name begins with an uppercase letter, followed by lowercase letters. That is, a function name is comprised of one or more capitalized words or abbreviated words.

Function names must be sufficiently mnemonic to convey their usage in the program in which they appear. Typically, this means that a function name is one or more descriptive English words or abbreviated words. Occasionally, short function names are satisfactory. Note well that a short function 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 functions.

Function Declarations

The following general template defines the format of a function declaration:

////
//
// Prose description ... .
//
// Precondition: ...
//
// Postcondition: ...
//
////
ReturnType SomeFunction(ParmType1 p1, ..., ParmTypem pm);

The Prose description describes what the function does, not how it is implemented. The input and/or output use of each parameter is described, using the parameter name that appears in the declaration. The return value, if any, is also described. Details of the format for preconditions and postconditions are discussed in CSC 101 Lecture Notes Week 9.

Function Definition Size

The body of a function is no more than 25 lines, excluding comments, variable declarations, and blank lines. This rule cannot be achieved by condensing lines in such a way as to violate any of the preceding formatting conventions. For example, the following is legal

for (i=1; i<=n; i++) {
    if (i % 2) {
        Foo1(i);
        Foo2(i);
    }
}

for (i=1; i<=n; i++) { if (i % 2) { Foo1(i); Foo2(i); } }

for (i=1; i<=n; i++) {
    if (i % 2) {
        Foo1(i);
        Foo2(i);}
}

Typedef Names

The names of types defined with typedef obey the same conventions as function names.