Comments should be descriptive. This is, they should clearly explain the purpose and meaning of the code to which it refers. The following code fragments illustrate what is and is not acceptable:
Not acceptable:
--------------------------
.............
unsigned char data;
// variable data
int start = 0xD0000;
// start = D0000
int end = 0xD4000;
// end = D4000
int i;
..............
for (i = start; i <= end; i++)
// For loop
{
data
= inportb(i);
// put the contents of i into data
data++;
// add one to data
outportb(i,
data);
// put data into location i of memory
}
...............
--------------------------
While the comments in the above code are not terrible, they do not indicate the purpose of the code. It can often be hard where to draw the line between too many unnecessary comments and enough comments to illustrate that you understand what is going on. Make sure that you provide comments that would allow another programmer to understand what the overall functionality of your code is.
Acceptable:
--------------------------
.............
unsigned char data;
// variable to store the 8 bit vals from memory
int start = 0xD0000;
// starting address in memory
int end = 0xD4000;
// ending address in memory
int i;
..............
/* Increment each location in memory by
1 beginning with the address 'start' and continuing to the address 'end'
according to the specification in lab description*/
for (i = start; i <= end; i++)
{
data
= inportb(i);
data++;
outportb(i,
data);
}
...............
--------------------------