Style and Documentation of Programs

Style and documentation is very important in this course. Although, there is no rigid rule for this purpose we would like your programs to be in the following format. The following is the list of things we will consider in grading your programs:

1) Header of the Program (Main and All Functions)

2) Variable Description

3) Code Block Description

4) Usefulness of the Comments

5) Indention (Note : DO NOT Use Tabs for Indentation)

6) Capitalization

1) Header :

The header of program should give some information about you and the program itself. This header must be clear and informative and does not contain redundant information. Follow is an example of a reasonable header.

Example :

/*

**************************************************************

* Name : Rahman Tashakkori

* Course : Phys 200

* Section : 01

* Program No . : Program 1

* Program Due Date : Sept. 8, 1998

* Description of the program:

* This Program is written for conversion of temperatures in degree Fahrenheit to Celsius. Users should provide the input file containing the input temperatures. This program uses directives to read the input file and to write the output.

* Example of input file :

0.0

212.0

* Example of output file :

32.0

100.0

* Example of running the program : a.out < input > output

**************************************************************

*/

Note that all functions in your program should have a header describing what that function does. You do not need to include information regarding yourself on the header of the functions.

2) Variable Description

It is strongly recommended that you use variable names such that they represent the definition. For instance a variable that represents degree Fahrenheit could be called fahr or fah or even Fahrenheit. But sometimes you use a variables that are not obvious. Thus, you need to describe those variables. Note : describe variables only if their names are not obvious.

Example :

int i, j;

int f ; /* variable used as the flag that shows the end of calculation */

As you can see we did not use description for i and j. These two commonly represent loop index or counters.

3) Code Block Description

Give a brief description of what a block of your program does. This comment must be very brief but informative.

Example :

for (i =0; i < N, i++) {

/* get in N temperatures in Celsius from keyboard, convert them to Fahrenheit, and print them out */

scanf(" %lf",&cel);

far = (9.0/5.0)*(cel)+32.0

printf(" %lf",cel);

printf(" in Celsius is = ");

printf("%lf ",far);

printf(" in Fahrenheit \n");

}

4) Usefulness of the Comments

Comments must be very informative and useful. The comment in the above example looks very simple but useful and informative. Lets' look at an example of bad comment.

for (i =0; i < N, i++) {

/* A for loop that go from 1 to 0 and change the value of far every time and will print out the result */

scanf(" %lf",&cel);

far = (9.0/5.0)*(cel)+32.0

printf(" %lf",cel);

printf(" in Celsius is = ");

printf("%lf ",far);

printf(" in Fahrenheit \n");

}

This comment just defines the for loop again and will not give any information of why it is there and what that block of program is suppose to do.

5) Indention (Note : DO NOT Use Tabs for Indentation)

indentation will increase the readability of the program. It is very important that we follow it as careful as possible. The indentation style is very clear. Every time you will start a new block go inside by 3-4 blank space and come back to the left most by the same number of balk spaces as you finish a block.

Example :

main()

{

int i;

double far, cel;

for (i =0; i < N, i++) {

/* A for loop that go from 1 to 0 and change the value of far every time and will

print out the result */

scanf(" %lf",&cel);

far = (9.0/5.0)*(cel)+32.0

printf(" %lf",cel);

printf(" in Celsius is = ");

printf("%lf ",far);

printf(" in Fahrenheit \n");

}

while(i <= 20) {

if (i < 10) {

printf(" %d",i);

printf("i is less than 10 \n");

}

else {

printf(" %d",i);

printf("i is equal to or larger than 10 but less than or equal to 20 \n");

}

}

printf("End of this program \n");

}

6) Capitalization

#define and enumerated type values must be all upper-case.

Example :

#define N 10

Or

typedef enum resp(TRUE, FALSE)