General discussion
We are going to consider a simple program that might be used for testing a compiler to make sure that it is installed correctly.
Compiler_test.cpp source code
//******************************************************
// Filename: Compiler_Test.cpp// Purpose: Average the ages of two people
// Author: Ken Busbee; © Kenneth Leroy Busbee// Date: Jan 5, 2009
// Comment: Main idea is to be able to// debug and run a program on your compiler.
//******************************************************// Headers and Other Technical Items
#include<iostream>using namespace std;// Function Prototypes
void pause(void);// Variables
int age1;int age2;
double answer;//******************************************************
// main//******************************************************
int main(void){
// Inputcout<<"\nEnter the age of the first person --->: ";
cin>>age1;
cout<<"\nEnter the age of the second person -->: ";
cin>>age2;
// Processanswer = (age1 + age2) / 2.0;
// Outputcout<<"\nThe average of their ages is -------->: ";
cout<<answer;
pause();return 0;
}//******************************************************
// pause//******************************************************
void pause(void){
cout<<"\n\n";
system("PAUSE");cout<<"\n\n";
return;}
//******************************************************// End of Program
//******************************************************
Within the programming industry there is a desire to make software programs easy to maintain. The desire centers in money. Simply put, it costs less money to maintain a well written program. One important aspect of program maintenance is making source code listings clear and as easy to read as possible. To that end we will consider the following:
- Documentation
- Vertical Alignment
- Appropriate use of Comments
- Banners for Functions
- Block Markers on Lines by Themselves
- Indent Block Markers
- Meaningful Identifier Names Consistently Typed
- Appropriate use of Typedef
The above items are not needed in order for the source code to compile. Technically the compiler does not read the source code the way humans read the source code. But that is exactly the point; the desire is to make the source code easier for humans to read. You should not be confused between what is possible (technically will compile) and what is ok (acceptable good programming practice that leads to readable code). Let's cover each item in more detail.
Documentation
Documentation is usually placed at the top of the program using several comment lines. The amount of information would vary based on the requirements or standards of the company who is paying its employees or independent contractors to write the code. Notice the indication of revision dates.
Vertical alignment
You see this within the documentation area. All of the items are aligned up within the same column. This vertical alignment occurs again when the variables are defined. When declaring variable or constants many textbooks put several items on one line; like this: