CS 596 OODP
Commenting Programs

1. References
2. Comments
   1. Kinds of Comments
   2. Commenting Efficiently
   3. Commenting Techniques
      1. Commenting Individual Lines
      2. Commenting Paragraphs of Code
   4. Commenting Data Declarations
   5. Commenting Routines

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 ' );

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 ' );

• 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

• 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

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

/* if allocation flag is zero */

if ( AllocFlag == 0 ) ...

/* if allocating a new member */

if ( AllocFlag == 0 ) ...

/* if allocating a new member */

if ( AllocFlag == NEW_MEMBER ) ...

{ 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;

{ 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;

{ find the command-word terminator }

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

while ((not FoundTheEnd) and 
       (Index <= MaxCommandLength)) begin

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

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

procedure InsertionSort 
	{
	Var	Data:		SortArray;    { sort array elements }
		FirstElement:	Integer	     {index of first element to sort}
		LastElement:	Integer	     {index of last element to sort}
	}