Why have programming style guidelines?

Programs are modified during their lifecycle - this is a fact. Most entry-level programmers will be asked to modify or enhance existing code as their first programming assignment when starting a new job. One estimate states that as much as 80% of the cost of software development is incurred by modifications that are completed during the so-called maintenance period of the software lifecycle. Most of the time, the person making software modifications is NOT the original author. Well-written code, code that can be understood, will make maintenance easier for everyone, saving time and money. The goal of programming guidelines is to make code more understandable.

The guidelines will be divided into three sections: code layout for readability, identifiers, and documentation.


I. Code Layout for Readability

The main areas of concern when looking at code layout are the appropriate use of white space and indentation.

A. Use of White Space

White space (blank lines and spaces) makes code more readable by spreading it out. Here are some general rules that, when followed, will make your code more readable and easier to understand.

dayCount = yearCount * 365;

B. Indentation and Braces

Indentation is used to identify major sections of a program. Statements within the main block should be indented. Indentation should also be used to indicate that some statements are executed as the result of the success or failure of test conditions. Loop bodies and if-then, if-then-else constructs are prime examples. When continuing a statement across multiple lines, the second and subsequent lines should be indented.

Many different indentation patterns are commonly used. A good recommendation is to indent each code block by one tab stop. Above all, be consistent.

Another visual clue to the structure of a program can be added by the appropriate and consistent use of braces ({}). Use the following guidelines for the proper placement of braces:

if (dayCount <= 365) {

or

if (dayCount <= 365)
{
if (dayCount <= 365)
{
    // do something
}
if (dayCount <= 365)
{
    // do something
}
else
{    
    // do something
}
for (int i=0; i<20; i++)
{
    // do something
}
while (i<20)
{
    // do something
}

II. Identifiers

Every variable, constant, class, and function used in a program must first be declared and given a symbolic name. Any symbolic name may be chosen as long as it is recognized as a legal identifier by the C++ compiler. The selection and use of meaningful names can make a program much more understandable by others. Here are some guidelines for declaring identifiers:

int dayCount = 0;
const int DAYS_IN_WEEK = 7;

III. Documentation

Documentation in the general sense refers to all written material that helps to explain the use and maintenance of a software system or program. Programs should have a certain amount of documentation embedded within them in the form of prologues and in-line comments.

The source code of each programming assignment should begin with a prologue in the following form:

/***************************************************************************
**
** Programmer: Your Name
**
** Date: Date Written
**
** Course: CSCI 201 Section 1
**
** Assignment: HomeWork Assignment 1
**
** Description: Description_of_assignment_goes_here
**
**
**************************************************************************/

The description should include what the program does and doesn’t do, what input is expected, what output will be generated, and any assumptions that the program makes.