Handout 3

CS260 Programming Standards*

Comments:

1. Every file must have a comment header at the top of the file, which includes:
   • filename,
   • assignment number,
   • author's name,
   • due date,
   • course number (such as CS260),
   • semester (such as Spring, 2001),
   • programming language dialect/IDE (such as Visual C++ 6.0), and
   • description of contents of file.
2. Every function (including the main function) must include comments which describe:
   • function description.
   • return type (if applicable),
   • input parameters names, types, and descriptions,
   • output parameters names, types, and descriptions, and

Variable Names:

1. Use self-documenting identifier names (for constants, variables, types, subprograms, ...).
   • Bad Example:
        float p, r;
        int h;
           ...
           p = h * r;
   • Good Example:
        float pay, hourlyRate;
        int hoursWorked;
           ...
           pay = hoursWorked * hourlyRate;
2. No global variables (but global named constants are permissible).
3. Use named-constants rather than literal-constants (if a value will not change during run-time assign it to a constant rather than a variable).
   • Bad Example:
        if (income < 10360) ...
   • OK Example (old style C):
        #define POVERTY_LINE 10360
           ...
           if (income < POVERTY_LINE) ...
   • Good Example:
        const int POVERTY_LINE = 10360;
           ...
           if (income < POVERTY_LINE) ...
4. Use appropriate data types (such as declare all index variables as integers, not as a floating-point type).
5. Use language constructs that correspond to the logical structure.
   1. Bad Example:
         if (hoursWorked < 40)
            pay = hoursWorked*hourlyRate;
         if (hoursWorked >= 40 && hoursWorked < 60)
            pay = 1.5*hoursWorked*hourlyRate - 20*hourlyRate;
         if (hoursWorked >= 60)
            pay = 2*hoursWorked*hourlyRate - 50*hourlyRate;
   2. Good Example:
         if (hoursWorked < 40)
            pay = hoursWorked*hourlyRate;
         else if (hoursWorked < 60)
            pay = 1.5*hoursWorked*hourlyRate - 20*hourlyRate;
         else
            pay = 2*hoursWorked*hourlyRate - 50*hourlyRate;
   • Note: absolutely no goto-statements are allowed (unless you can convince the instructor of its necessity).
6. Variable and function names:
   • Variable and function names will be in all lowercase letters; constant macro names will be in all uppercase letters.
   • You may use the underscore character (_) to improve readability of your names.
   • The newer naming conventions in coding use mostly lowercase letters. In this style,variable names must begin with a lowercase letter, with embedded words beginning with a capital letter, as in nbrUppercase. If a concatenated word is easy to read, all letters can be lowercase. For example, bignum and bigNum are both acceptable, as are nbrUppercase and nbrUpperCase.

Indenting

For block structured procedural languages like C, Pascal or Ada, the body of a loop (while loop, for loop, do loop, repeat until loop or any other looping construct) should be indented. Code that is conditionally executed (from an if statement or other decision statement) should be indented. The level of indentation should be equal to the nested depth of the code.

Comments

Use comments generously to tell in English what your program is doing. They are to be used to describe the purpose of a program (in the header from guideline #1), of each defined variable and constant macro (see guideline #3), of each function within the program (see text), and of any other key program segment. However, comments must be meaningful, that is, quality is as important as quantity. For example, vacuous comments like

			a = b + c;   /* Add b and c and store in a */

tell us nothing of value and should be avoided (they also do NOT make up for the lousy choice of variable names!).

Spacing

• Leave a space before and after each special symbol. C syntax does not require this, but failure to do so can lead to unreadable programs. These symbols include (but may not be limited to) =, after ; and before and after arithmetic and relational operators.
• Use blank lines to separate program "parts", for example, reprocessor directives from the main function heading, variable declarations from function code. If unsure where to leave blank lines, err on the side of too much white space, not too little.

Goals:

1. The goal of a comment is to explain; "what the program does, not how it is done".
   • Comments should:
     • be a higher-level of abstraction than the actual code,
     • describe blocks of code, rather than commenting every line (except for a line of code that is particularly unusual),
     • use blank lines or indentation so that comments can be readily distinguished from code, and
     • be correct; an incorrect or misleading comment is worse than no comment at all.
2. Use appropriate data structures.
3. Use appropriate algorithms.
4. Each programmer-defined ADT should be implemented within a separate file (which includes data representations and method implementations).
5. Functions should not be more than one printed page long (about 60 lines).

Example (code available here)

// filename: avg.cpp
// assignment: MP05
// author: Ada Lovelace
// due date: March 25, 2525
// course: CS260
// semester: Spring, 2525
// IDE: Microsoft Visual C++ 6.0
// description: The avg function returns the arithmetic mean of a vector of 
//              numvalues items. If numvalues is less than 1, the result is 0.

#include <cmath>

// function prototypes
float avg(float [], int);

// Define program limits
const int MAXNUM = 100;

// The avg function returns (float) the arithmetic mean of a vector of 
// numvalues items. If numvalues is less than 1, the result is 0.

float avg( float x[MAXNUM],        // in: array of data values
           int numvalues ) {       // in: number of values in x 

        float sum;      // sum of the data values  
        int     i;      // index into input array x  

        if (numvalues > 0) {    // check for empty vectors 
                
                sum = 0.0;      // initialize sum 

                for (i = 0; i < numvalues; i++)
                        sum += x[i];    // sum all values in array x 

                return (sum / (float)numvalues);
        }

        else    // mean of nothing is zero 

        return (0.0);
}