CODE PRESENTATION AND MAINTENANCE

Aims

To enable students to:

· provide meaningful variable names

· use indentation to indicate program structure

· use case to improve program readability

· handle comments

· generate appropriate documentation

Provide meaningful variable names

All computers store information to be manipulated in memory, each location having a unique numeric address. Sometimes the information to be stored is small (such as a char) and will only occupy one memory location, other items may be much larger and require several adjacent ones. To aid development C++ permits developers to associate a meaningful name with information being stored, protecting them from the actual addresses used.

Address	Memory location	Variable name

0
1		cFirstCharacter
2
3
4
5		iFirstNumber

There are few restrictions on the names a programmer may use for variables. The name must start with a letter or underscore (_) character, optionally followed by one or more further letters, underscores or digits. Further, the final name may not match a C++ keyword. Some compilers only examine the first eight characters of a variable name, so it pays to ensure that all variables differ within this area.

It is not permissible to place spaces into variable names - the compiler uses them to recognise the beginning and end of program statements. Instead, if a space is required either use the _ character or capitalise the first letter of the next word. For example if you wish to call a variable cDays of the week the following would be acceptable definitions:

char cdays_of_the_week;

char cDaysOfTheWeek;

C++ is case sensitive, so it is possible to declare two variables of the same name but different case, such as name and NAME. The compiler will correctly distinguish these two variables, but the developer is likely to get confused - avoid this practice!

Variable names should always be chosen carefully to aid both the developer and those who succeed to follow the source code.They should reflect the data they hold, for example an integer that holds an identification number for a product may be called iProductNumber;

It is common for the data type of the variable to be indicated by the first character of the variable name - c for char, i for integer, f for float, etc.

Use indentation to indicate program structure

The C++ compiler converts source files into object code. As a computer program it is unconcerned with the legibility of the code, but humans do not have this ability - consistent spacing within the file is essential for them. The following two code fragments will be happily processed by the compiler, but one is much easier for humans to handle than the other.

Fragment 1:

int iNumber1;

iNumber1 = 17;

Fragment 2:

int

iNumber1;

iNumber1=

;

Logical blocks within a program, such as functions, loops, decision blocks, etc. are enclosed by { } braces. It is common practice to line the braces of a logical block up, such that the opening and closing brace are above one another. Code within these blocks is indented so the logical block may be easily seen. An example:

void main ()

{

cout << “Hello, “;

cout << “world\n”;

}

Blocks of code may be nested (don’t worry that you have not yet met the for loop), as in:

void main ()

{

cout << “Hello, “;

cout << “world”;

for (int x = 0; x < 10; x++)

{

cout << “!”;

}

cout << “\n”;

}

Indentation is used to make the logic/structure of the program easier to follow for humans, it has no effect on the compiler, output from the program or eventual execution speed.

To save space on the screen it is common to use an indentation of 3 characters, i.e. statements within braces are indented 3 spaces from the braces.

Use case to improve program readability

Besides using indentation to make program source code easier to follow, consistent use of case can make a big difference. All C++ keywords must be written in lower case.Examples include; for, if, while, etc.

Variables and function names are usually lower case, an exception being where the developer wishes to use a number of words in a variable or function name (for example fValueOfPi) in which case mixed case is permitted. Examples include:

int icolour;

float fCurrentTemperature;

Preprocessor declared constants or constant variables are usually written in upper case, for example:

#define MAXIMUM_LENGTH 47

const int AGE = 65;

Consistent use of case permits developers to differentiate between constants, variables and functions.

Handle comments

A comment is text placed into source code with the intention of providing notes to developers and future maintainers. Anything can be placed within comments as the compiler will ignore them. A well structured C++ source file should contain plenty of comments.

There are two flavours of comments, blocks and lines.

A comment block is started with /* and ended with */. All text between these markers is ignored, whether it covers 1, 10 or 100 lines. Comment blocks are often used to describe code that is to follow, for example it may describe the purpose of a function, when it was written, etc. as in the following:

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

/**/

/* Function name: main*/

/**/

/* Description: Main function of the program.*/

/**/

/* Parameters: none*/

/**/

/* Returns: none*/

/**/

/* Change History:*/

/**/

/* 10/10/1998 Function creation by RF*/

/**/

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

void main ()

{

cout << “Hello World\n”;

}

A comment line begins with // with the compiler ignoring everything that follows on the current line. These may exist on a line of their own or at the end of a line processed by the compiler, for example:

void main ()

{

// Display a message to the user

cout << “Hello World\n”; // Send messageto the screen

}

It is perfectly acceptable to nest comments within each other.

Generate appropriate documentation

Programmers should always make the operation of their program as easy and straight forward as possible for the end user. A major step forward in this area is to provide clear and unambiguous user instructions for the operation of the program, both succinctly on screen and in accompanying paper documentation.

Accompanying paper documentation should also include notes to developers describing the purpose and operation of the program.

Appropriate developer documentation should be included within the source file in the form of comments.