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.
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.
- Don't put more than one statement on a line.
- Use spaces between operands and operators in expressions.
dayCount = yearCount * 365;
- Put spaces after commas.
- Keep lines 76 characters or less in length; break and indent longer lines (see indentation rules).
- "Paragraph" your code by grouping statements that perform a task and by putting blank lines between groups.
- Use parentheses liberally. When in doubt, use them. They leave no doubt as to what order things will be done.
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:
- Opening braces should either be at the end of the line containing the command that begins a code segment or aligned with the command on the line immediately following.
if (dayCount <= 365) {or
if (dayCount <= 365) {
- Closing braces should be on their own line aligned with the command that began the code segment.
if (dayCount <= 365) { // do something }
- else appears on the line after the brace that closes the if
if (dayCount <= 365) { // do something } else { // do something }
- for loops are formatted like the if
for (int i=0; i<20; i++) { // do something }
- while loops are formatted like the if
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:
- Declare and initialize variables as close as possible to the point of first use.
- Identifier names should be chosen to indicate the use of the variable.
int dayCount = 0;
- Names of constants should be in upper case.
const int DAYS_IN_WEEK = 7;
- Single letter variable names should only be for such things as loop counters.
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 doesnt do, what input is expected, what output will be generated, and any assumptions that the program makes.