## CS 596 OODP Commenting Programs

[To Lecture Notes Index]
San Diego State University -- This page last updated September 12, 1995

## References

Code Complete, Steve McConnell, Microsoft Press, 1993, chapter 19, p 453-488

Note these notes follow very closely the chapter in Code Complete. Nearly all examples are taken directly from Code Complete. I have used the same headers and main points of the text.

What does this do?
```for i := 1 to Num do
MeetsCriteria[ i ] := True;
for  i := 1 to Num / 2  do begin
j := i + i;
while ( j <= Num ) do begin
MeetsCriteria[ j ] := False;
j := j + i;
end;
for i := 1 to Mun do
if MeetsCriteria[ i ] then
writeln( i, ' meets criteria ' );

```

How many comments does this need?
```

for PrimeCandidate:= 1 to Num do
IsPrime[ PrimeCandidate] := True;

for  Factor:= 1 to Num / 2  do begin
FactorableNumber := Factor + Factor ;
while ( FactorableNumber <= Num ) do begin
IsPrime[ FactorableNumber ] := False;
FactorableNumber := FactorableNumber + Factor ;
end;
end;

for PrimeCandidate:= 1 to Num do
if IsPrime[ PrimeCandidate] then
writeln( PrimeCandidate, ' is Prime ' );

```
Good Programming Style is the Foundation of Well Commented Program

• Repeat of the code
```X := X + 1 	/* add one to X

/* if allocation flag is zero */

if ( AllocFlag == 0 ) ...
```

• Explanation of code
Used to explain complicated or tricky code
```*p++->*c = a

/* first we need to increase p by one, then ..
```
Make code simpler before commenting
```(*(p++))->*c = a

ObjectPointerPointer++;
ObjectPointer = *ObjectPointerPointer;
ObjectPointer ->*DataMemberPointer = a;
```
• Marker in the code
```/*  **** Need to add error checking here  **** */

```

• Summary of the code
Distills a few lines of code into one or two sentences
• Description of the code's intent
Explains the purpose of a section of code
```{ get current employee information }   intent

{ update EmpRec structure }     what
```

### Commenting Efficiently

• Use styles that are easy to maintain
```/***********************************
* module: Print                   *
*                                 *
* author: Roger Whitney           *
* date:   Sept. 10, 1995          *
*                                 *
* blah blah blah                  *
*                                 *
***********************************/

/***********************************
module: Print

author: Roger Whitney
date:   Sept. 10, 1995

blah blah blah

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

```
• Comment as you go along

### Commenting Techniques

#### Commenting Individual Lines

```MOV AX,  723h	     ;    R. I. P. L. V. B.
```

```MemToInit := MemoryAvailable(); { get memory available }
```

Not much room for comment
Must work to format the comment

Data declarations
Maintenance notes
Mark ends of blocks

#### Commenting Paragraphs of Code

Write comments at the level of the code's intent

Comment the why rather than the how

Make every comment count

Document suprises

Avoid abbreviations
How verses Why
How
```/* if allocation flag is zero */

if ( AllocFlag == 0 ) ...
```

Why
```/* if allocating a new member */

if ( AllocFlag == 0 ) ...
```

Even Better
```/* if allocating a new member */

if ( AllocFlag == NEW_MEMBER ) ...
```

Summary comment on How
```{ check each character in "InputStr" until a
dollar sign is found or all characters have
been checked }

Done   := false;
MaxPos := Length( InputStr );
i      := 1;
while ( (not Done) and (i <= MaxLen) ) begin
if ( InputStr[ i ] = '\$' ) then
Done := True
else
i := i + 1
end;

```

Summary comment on Intent
```{ find the command-word terminator }

Done   := false;
MaxPos := Length( InputStr );
i      := 1;

while ( (not Done) and (i <= MaxPos ) ) begin
if ( InputStr[ i ] = '\$' ) then
Done := True
else
i := i + 1
end;

```

Summary comment on Intent with Better Style
```{ find the command-word terminator }

FoundTheEnd      := false;
MaxCommandLength := Length( InputStr );
Index            := 1;

(Index <= MaxCommandLength)) begin

if ( InputStr[ Index ] = '\$' ) then
FoundTheEnd := True;
else
Index := Index + 1;
end;
```

### Commenting Data Declarations

Comment the units of numeric data

Comment the range of allowable numeric values

Comment coded meanings
```var
CursorX:		1..MaxCols;	{ horizontal screen position of cursor }
CursorY:		1..MaxRows;	{ vertical position of cursor on screen }

AntennaLength:	Real;	{ length of antenna in meters: >= 2 }
SignalStrength:	Integer;	{ strength of signal in kilowatts: >= 1 }

CharCode:		0..255;	{ ASCII character code }
CharAttib:		Integer;	{ 0=Plain; 1=Italic; 2=Bold  }
CharSize:			4..127;	{ size of character in points }

Comment limitations on input data

Document flags to the bit level

```

### Commenting Routines

Avoid Kitchen-Sink Routine Prologs

Keep comments close to the code they describe

Describe each routine in one or two sentences at the top of the routine

Document input and output variables where they are declared

Differentiate between input and output data

Document interface assumptions

Keep track of the routine's change history

Comment on the routine's limitation

Document the routine's global effects

Document the source of algorithms that are used
```procedure InsertionSort
{
Var	Data:		SortArray;    { sort array elements }
FirstElement:	Integer	     {index of first element to sort}
LastElement:	Integer	     {index of last element to sort}
}

```