Computer Science
|
|
Program Standards
Read this document frequently. Remember that style is for people, not the machine. Correct use of identifiers, white space and documentation makes your program easier to understand for those humans reading it. Since you also will be reading your own program, you will want to be consistent and current with your documentation.
Properties of good style
- Programs that are easy to read and understand.
- Programs that communicate the algorithm used in a form easy to follow.
- Programs that are easy to modify and enhance to adapt to new and changing environments. (It is important to keep in mind that the programmer making the modifications may not be the initial author.)
Principles of good style
There are many good and acceptable styles. There will be examples of some below. The examples in your textbook also illustrate good style. There are some strict rules that all good programmers follow but there are many rules, those concerning indentation, for instance, which may be adapted to personal style, but within limits. When writing your programs, it is important to be consistent with use of indentation, white space and documentation throughout your program. Develop a style that works for you but also fits acceptable programming standards.
- Clarity and simplicity
Avoid unnecessary complexity. When possible, use the straight forward method. Don't sacrifice clarity for cleverness.
- Use meaningful identifiers
Choose names for constants, variables, functions, etc., that accurately describe the purpose of the identifier. For instance, a, x, t are poor identifiers because they are meaningless whereas age, salary, and first_name are good choices. Constants should be all uppercase. Other identifiers should make use of the underscore "_" and uppercase letters to distinguish the words in an identifier (FirstName or first_name but not firstname).
- Avoid use of "magic" numbers
Don't use numbers like 50 or 1024 within your program. Use constants or variables so that they can be easily changed. For example, a program that computes the grades for 50 students this semester can be altered more easily if there is a constant named CLASS_SIZE used throughout the program rather than the number 50.
- One statement per line
Needs no further explanation!
- Use proper indentation of control structures
Be consistent with indentation. There are several styles to choose from but whichever you choose, be consistent!. Some examples are given below. Note the placement of the curly braces and the code.
Style I
if (expression) {
x = 3;
}
else {
y = 3;
} // if |
while (expression) {
x = 3;
} // while |
for (i = 0; i < MAX; i++) {
x = x + i;
} // for |
do {
x = 3;
} while (expression); // do |
int Maximum(int x, int y) {
if (x > y) {
return x;
}
else {
return y;
} // if
} // Maximum |
Style II
if (expression)
{
x = 3;
}
else
{
y = 3;
} // if |
while (expression)
{
x = 3;
} // while |
for (i = 0; i < MAX; i++)
{
x = x + i;
} // for |
do
{
x = 3;
} while (expression); // do |
int Maximum(int x, int y)
{
if (x > y)
{
return x;
}
else
{
return y;
} // if
} // Maximum |
- Use block comments and white space
Simply leaving a line blank before and after a group of statements that performs a specific task makes the program more readable as well as separates one task from another. Block comments should be used to explain what a group of statements do. There are two common ways to put block comments in your program, illustrated below. Be consistent!
//********************************************************
// In the first style, each line begins with two forward
// slashes, and the asterisks on first and last clearly
// designate the beginning and end of the block
// comment
//******************************************************** |
/*********************************************************
In the second style the "slash star" begins the comment
and the "star slash" ends the comment. As before the
rows of asterisks designate the beginning and end of
the block comment
*********************************************************/ |
Block comments may be used throughout the program but must appear at the beginning of the program and with each function declaration.
The block comment at the beginning of the program should include information about the programmer and the program (purpose, compiler, date of completion, course). The following is an example:
//***********************************************************
// Programmer: Mickey Mouse
// Program: Obtains and stores names of new members
// the Mickey Mouse club updating
// the master file "Membership.dat"
// Compiler: Microsoft Visual C++, version 6.0
// Date: March 13, 1999 (original completion)
// Modified: January 5, 2001 by D. Duck
// Assisted by: You MUST provide who helped and with what!
//*********************************************************** |
- Use modularity
Good programming style requires writing modules (in our case, functions) so that the program is more clearly understood and more easily debugged and modified. Good use of modularity means:
- Have the main program closely resemble the high level solution to the problem.
- Break the code into cohesive units keeping only code that logically belongs together in the same module. Modules should not become very long.
- Use information hiding to hide the details of a task in a single module.
- Define the purpose of the module, each formal parameter and all major global variables.
The block comment for each function must contain information about what the function does, what it gets, what it returns, special features, etc. An example appears below:
//***********************************************************
// Function: Sort
// Purpose: Sorts the entries in the name array into
// alphabetical order.
// Entry Conditions:
// name - array of names as the appear in file
// size - number of names actually in the array
// Exit Conditions:
// name - array of names sorted in ascending order
// Global:
// MAX_SIZE - size of array of names
// Special Note: The sorting algorithm used is the BubbleSort
// Called By: function main()
//***********************************************************
void Sort(string name[], int size) |
|
|
