<< Chapter < Page Chapter >> Page >
A source code listing and discussion of several items that make source code easier to read and maintain.

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 //******************************************************

Got questions? Get instant answers now!

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:

  1. Documentation
  2. Vertical Alignment
  3. Appropriate use of Comments
  4. Banners for Functions
  5. Block Markers on Lines by Themselves
  6. Indent Block Markers
  7. Meaningful Identifier Names Consistently Typed
  8. 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:

Get Jobilize Job Search Mobile App in your pocket Now!

Get it on Google Play Download on the App Store Now




Source:  OpenStax, Programming fundamentals - a modular structured approach using c++. OpenStax CNX. Jan 10, 2013 Download for free at http://cnx.org/content/col10621/1.22
Google Play and the Google Play logo are trademarks of Google Inc.

Notification Switch

Would you like to follow the 'Programming fundamentals - a modular structured approach using c++' conversation and receive update notifications?

Ask