CS 180 C++ Programming Standards

(This page last modified August 19, 1997.)

The following standards are to be followed in writing C++ programs. They are important enough to be part of the grading criteria for all programs. Any constructs not covered in this standard are to be implemented in a consistent and readable fashion.

PURPOSE

The purpose of these rules are (1) to introduce you to a representative set of coding standards that are typical in professional programming and (2) to help you develop good style as a habit, something you will find necessary to successfully complete large programs. There is no doubt that you can write C++ programs to solve the small problems in this course without attention to style. But, you must keep in mind that you are building professional skills, not merely finding the answers to problems handed out as exercises.

FILE NAMES AND C++ COMPILER

In this course each C++ file name should clearly represent what it is and each should have the ``.cc'' suffix. For example, Project 1 should be proj1.cc or project1.cc. A lab project that determines the payroll of a small company could be payroll.cc (or even something like lab3.cc). We will use the g++ compiler. So, in order to compile Project 1, you would type the command g++ proj1.cc

INTRODUCTORY DOCUMENTATION

At the beginning of each program there should be a comment block that contains:

The program name, your name, and recitation section.
A brief description of the program that describes the method or algorithm used to obtain the solution, the major data structures (if any) in the program, and other general comments including extra features.
The date the program was completed.

The format to be used is as follows:

//******************************************************************* 
//                                                                    
//  Program:  program name                                            
//                                                                     
//  Author:  your name                                             
//                                                                    
//  Recitation Section:  section number and instructor's name
//                                                                    
//  Description:  brief description of the program                    
//                                                                    
//  Date:  date of completion
//                                                                    
//*******************************************************************

The following is an example of an introductory comment block that follows the format above:

//******************************************************************* 
//                                                                    
//  Program:  Project 1 -- Video Calculator
//                                                                     
//  Author:  Elwood Scuggins                                    
//                                                                    
//  Recitation Section:  10 (Daniels)
//                                                                    
//  Description:  This program inputs the total number of minutes, 
//                the number of minutes for commercials, and the 
//                number of minutes for episodes.  The program 
//                computes the total number of minutes for videos, 
//                the number of videos, and the number of seconds 
//                left over.
//                                                                    
//  Date:  September 26, 1997
//                                                                    
//*******************************************************************

DECLARATIONS

You should use mnemonic names for all identifiers. These are names that have meaning in the problem. The names should suggest the use of the identifier. Underscore characters should be used to delimit multiple words in an identifier. For example, ship_rates instead of shiprates, id_entry instead of identry, num_items instead of numitems, and min_score instead of minscore.

Constant values used in your program will be given in const declarations. Constant identifiers should always appear in all-capital letters. For example:
const float BASE = 2.0; // divisor to obtain base 2 const char HYPHEN = '-'; // signals word continued on next line const int NAME_LENGTH = 20; // names can be 20 characters

Structs and classes should begin with a capital letter (for example, Date, Vehicle, Software_engineer).
Variables should be all-lower case letters (for example, student, temperature, weight, salary, ship_rates, min_score).
Each identifier declaration (including function declarations) must be accompanied by a comment that explains its use.
Avoid declaring globally-visible variables. Globally-visible constants, enumerated types, structures, classes, and file names are okay, but do not use global variables unless the project assignment specifically tells you to do so.

GENERAL RULES

Each constant and variable declaration should be on a separate line that includes a comment that explains what each is. For example:
float volts; // voltage in the circuit int amps; // amperage in the circuit char circuit_name[NAME_LENGTH]; // name of the circuit

Each statement should be on a line by itself. For example, instead of
left = next_left; right = next_right;
use left = next_left; // move to the left right = next_right; // move to the right

Each function should be identified by a comment block describing its purpose, parameter(s), and the function(s) it calls. The format to be used is as follows: //****************************************************************** // // Function: find_space_cost // // Purpose: calculates and returns the charge for shipping cargo // between two planets. // // Parameters: distance - distance in miles between two planets // weight - weight in pounds of item being shipped // // Calls: function cargo_rates // //******************************************************************

Comments should be set apart from the code by at least two spaces, making it easy to see where the code ends and comment begins.
The main function should begin with
void main ()
even though that will lead to a warning from some C++ compilers.
Function prototypes should usually include the type and name of each parameter:
float expo (float value, int exponent);
But, it is also permissible to use only the parameter types since the C++ compiler ignores the names:
float expo (float, int);
Use the endl construction (instead of \n) to indicate end-of-line. For example, use
cout << "Today's date is " << today << endl;
instead of
cout << "Today's date is " << today << "\n";

FORMATTING AND COMMENTING OF STATEMENTS

Alignment and indentation of lines of C++ statements adds much to the readability of programs. The following guidelines are general so that you may develop your own programming style. Use indentation and blank lines as you see fit to increase the readability of your programs. Use whitespace (blank lines and spaces on lines) liberally! Use parentheses liberally!!

The body of a control structure, such as an if, a switch, a while, a do, or a for statement, should be indented. All of the following are acceptable formatting styles:

if statement

if (expression)
  {
   statements
  }
    

if (expression)
{
   statements
}
    

if (expression) {
   statements
}
    

if-else statement

if (expression)
  {
   statements
  }
else
  {
   statements
  }
    

if (expression)
{
   statements
}
else
{
   statements
}
    

if (expression) {
   statements
}
else {
   statements
}
    

switch statement

switch (selector variable)
  {
   case case-1-value: case 1 statements;
        break;
   case case-2-value: case 2 statements;
        break;
   ...
   case case-n-value: case n statements;
        break;
   default: default statements;
        break;
  }
    

switch (selector variable)
{
   case case-1-value: case 1 statements;
        break;
   case case-2-value: case 2 statements;
        break;
   ...
   case case-n-value: case n statements;
        break;
   default: default statements;
        break;
}
    

switch (selector variable) 
{
   case case-1-value: 
        case 1 statements;
        break;
   case case-2-value: 
        case 2 statements;
        break;
   ...
   case case-n-value: 
        case n statements;
        break;
   default: 
        default statements;
        break;
}
    

while statement

while (expression)
  {
   statements
  }


while (expression)
{
   statements
}


while (expression) {
   statements
}


do-while statement

do
  {
   statements
  }
while (expression);


do
{
   statements
}
while (expression);


do {
   statements
} while (expression);


for statement

for (initialization; test; increment)
  {
   statements
  }

for (initialization; test; increment)
{
   statements
}

for (initialization; test; increment) {
   statements
}

PROGRAM DESIGN

Use stepwise refinement. The programming assignments given are ones that can be solved in a step-by-step manner. The method of solution used in your program should exhibit this kind of structure.
Modularize your program. When a problem solution readily splits into distinct tasks, your program should handle each task in a separate function and in a straightforward manner.
Make your program efficient. Your algorithm should be direct and not unnecessarily complicated. Proper use of data structures will often simplify an algorithm.
Use parameters appropriately. All variables used in a function should either be declared as parameters or be declared locally within the function.

OUTPUT

All input values should be echoed in a readable manner unless otherwise indicated.
The program output should be readable and clearly labelled. Headings should be used when appropriate.
Finally, of course, your program should produce correct results!

Return to homepage of CS 180 -
Introduction to Computer Science