Comments and Indentation

Introduction

Including Comments

Indenting Your Code

Extension Work

Introduction

When writing a program, it is essential to remember that although you code may seem perfectly clear to you, your job is also to make it clear to other programmers. Moreover, you will find that if you go back to a piece of code you have written in the past, you will probably not understand it yourself. Why this is so I don't know, Whenever I view some of old code of my own, it look likes a confusing piece of madness although it was perfectly clear at the time.

There are two things that help with the understanding of a piece of work - comments and indentation. You can be sure that if you do not use these techniques to make your code clear you will irritate any programmer that has to subsequently work on you code. You wouldn't want that.

Including Comments

Comments are simply text ignored by the compiler. They help to inform the reader of what you are doing at any particular point in your program.

Including comments in your code helps to clarify your intentions. Believe me, comments are essential.

There are two ways of including comments in C++. Using // and using /*...*/

The double-slash comment // is used to write a comment on a single line.

The slash-star comment /* tells the compiler to ignore any text until it finds the opposite slash-star */. You must match every /* with it's pair */

Many C++ programmers use the double-slash style comment most of the time and reserve slash-star style comments for ignoring large sections of a program.

As a general rule, your program should have comments at the beginning, explaining what the program does. Each function should also have comments explaining what it does and what values it returns. Finally, any statements in your program that are obscure or less than obvious should be commented as well. You don't have to write comments on every line, especially if the line is obviously understandable.

Here is an example of commented code:-

/************************************************************
Program: Hello World

Files: HelloWorld.cpp

Author: ADR

Environment: Visual C++ 6 Enterprise, Windows XP

Notes: Contracted by Southwark College

Revisions: 1.00 07/08/03 First release

************************************************************/

#include <iostream.h>

int main() {

/*this is a comment to describe the purpose of the function. It extends until the closing slash-star */

cout << "Hello World!\n"; //this is a comment at the end of a line
return 0; //This comment line is unnecessary - the code is obvious
}

You will be expected to add comments to your own programs.

Indenting Your Code

Indenting your code helps with its readability. If you write every line of code against the left side it is difficult to read.

The rules of indentation are fairly straightforward. Lines of code inside every block should be indented by four spaces, or a tab. Any block within a block should further indent the code.

Here is an example of un-indented code. Don't worry about not being able to understand the code:-

int main() {
/*example to show code indentation*/
int loopAgain = 0; int userAns = 0; do { cout << "Enter 1 for a pizza, 2 for a burger";
//get the user's input
cin >> userAns; if (userAns == 1)//user wants pizza
{
cout << "You have ordered pizza" << endl; loopAgain = 0; } if (userAns == 2)//user wants a burger
{ cout << "You have ordered a burger" << endl; loopAgain = 0; } else loopAgain = 1; } while (loopAgain); return 0; }

Its not very easy to read is it?

Here is an example of the same code but indented. Believe me, this is much clearer!

int main() {
     /*example to show code indentation*/
     int loopAgain = 0;     int userAns = 0;     do {           cout << "Enter 1 for a pizza, 2 for a burger";

          //get the user's input
          cin >> userAns;          if (userAns == 1) //user wants pizza
          {                cout << "You have ordered pizza" << endl;                loopAgain = 0;           }          if (userAns == 2) //user wants a burger
          {                cout << "You have ordered a burger" << endl;                loopAgain = 0;           }          else loopAgain = 1;     } while (loopAgain);      return 0; }

Notice the indentation of any code inside blocks defined by the curly braces {}. I.e. the code inside main is indented by 1 tab. Then there is a do...while block. All code inside that is further indented by 1 tab. Then there are two if...else blocks. Code inside those blocks are indented again.

You will be expected to use indentation in your code.

Extension Work

Include comments and indentation in any programs you have written so far.

I.e. Your HelloWorld program.

Now move onto the next tutorial to start your second program - Hello Again.