The C++ Formatting Standards given below are to be used in this course. These standards have been approved by the department and are required for all programming assignments.
C++ allows for the use of free formatting and multiple statements per line. The excessive misuse of this, however, can lead to a program which is difficult to read. You should quickly adopt good habits of indentation to enhance the readability of your program and to highlight its logical structure.
There is no single ``industry standard'' for formatting C++ programs. Nonetheless, a guide for pretty printing is provided below for you to follow.
General Rules:
1. Each program must begin with a comment which identifies the program and the programmer. It should be formatted according to the following example:
// CIS 121 Section 01 // Assignment No. 1 // // Smith, Rosalynn // SSN 123-45-6789 // // This program takes as input the sale price and the percentage // reduction of a sale and outputs how much money one saves when // she buys an item on sale.
2. Use additional comments to ``Paragraph'' your C++ program in such a way that one can visually identify the logically related modules of the program. Use at least one blank line between modules.
3. Use comments that tell what or why something is being done, not how it is being done. Comments should be in simple English and be directed towards explaining the higher level algorithmic functions being performed.
4. Use meaningful identifiers for variables, types, procedures, and functions. For example, s, d, p should be replaced by names such as Sales, Discount, and Price.
Declarations:
1. Constant definitions and variable declarations are to appear in a ``data dictionary'' format. Each variable declaration should be on a separate line. Each line will include a comment specifying the usage and the meaning of each identifier. Note that this especially includes parameters to functions. Declarations should be formatted according to the following example.
// Constants:
const int ArrayLength = 50; // Size of array
// Variables (or objects):
int ArrayIndex, // Indexes into sort array
DayCount; // Day of week counter
float Temp; // Intermediate variable
char* Name; // User's name.
Note that it is char* Name and not char *Name.
2. No function with a non-void return value may alter any of its value parameters. No function may change the value of any global variable.
3. Each function must be preceded by a comment which describes the purpose of the program module.
Control Structures:
1. goto's are not allowed unless there is no other way to do the task.
2. Nesting of any combination of if, for, while and switch statements must be no more than four levels deep.
3. All lengthy (more than 6 lines) loops and switches must
have a comment after the last brace such as:
} //end for ...
4. If a block within a control statement is empty, use braces to denote an empty block rather than ending with a semi-colon.
General Pretty Printing Rules:
1. The spacing of any construct not specifically mentioned in this standard is left open to the user. The user is encouraged to insert extra blank lines beyond those given in this standard to promote readability.
2. Each statement must begin on a separate line. All { and }'s must appear on separate lines except for comments. Each } must be indented to the same level as it's matching {.
3. Each line must be less than or equal to 72 characters. Warning: just because it looks okay on your screen doesn't mean it will look good on others. Always type a return at the end of every line.
4. Use a modest amount of indenting per line. 3-4 spaces suffice. Do not use tabs. If your lines are indented so far over they no longer reasonably fit, it's time to create a function.
5. Comments that are appended to the end of a line of code and that are continued on successive lines must be written so that continued line starts under the initial comment fragment. Similarly with long statements such as assignments that need to be broken up. E.g.,
foo = blot * rot - 78; // Compute new value based on
// previous inputs.
6. At least one blank line must appear before declarations. At least three blank lines must appear before function and class declarations.
7. At least one space must appear before and after ``='' (assignment) and all two character operators (except ``->'' which may not have any spaces as well as ``.''). At least one space or newline must appear before and after each reserved word (except for) and before and after ``//'' in a comment
Alignment Rules:
1. Function and class headings begin at the left margin.
2. The main { ...} block of a function should be lined up with the corresponding heading.
3. For each of the following, the indenting style given
in Mercer must be used:
if, pages 189, 195.
compound statements and blocks, pages 133, 197.
switch, 212.
while, 242.
for, 280.
do while, 284.
class, 359.
Program Documentation:
Program documentation is essential to the proper development and maintenance of computer software. It is used to explicitly state what a program must do, what the program user must do to effectively utilize the program, and how each part of the program goes about doing what it does. Furthermore, it is necessary that these practices be developed early so that as the software developer matures these practices will become more refined. To this end, all programs should be well documented (as defined in the C++ Formatting Standards handout). Accompanying the documented program should be:
(1) the requirements specification,
(2) your top-down design for the problem,
(3) a sample of input data (when appropriate) and,
(4) a listing of the program's results.
The requirements specification for this course must include four sections:
Input: What data must the user provide to the program?
Processing: What processing of the input data is required?
Output: What data should be produced and displayed as a
result of the processing?
Assumptions: What can be assumed about how the program will be
used?
Top-down design/stepwise refinement is the chosen structured design for this course. Whether the design is submitted in outline or diagram form remains the instructor's choice.