CS 535 Object-Oriented Programming & Design Fall Semester, 2000 Assignment 2 Comments
	Previous    Lecture Notes Index    Next     © 2000, All Rights Reserved, SDSU & Roger Whitney San Diego State University -- This page last updated 09-Oct-00

Indentation, White space
Names
Comments

Commenting Efficiently
Kinds of Comments

Keep Code simple
Asserts
Testing
Try-catch
Points & Rectangles

Doc 11, Assignment 2 Comments Slide # 2

Indentation, White space

public Point getCenter()
{
return lowerLeft.add( upperRight).divide( 2);
} 
public Point getCenter()
{
 return lowerLeft.add( upperRight).divide( 2);
} 
public Point getCenter()
{
   return lowerLeft.add( upperRight).divide( 2);
} 
public Point getCenter(){
   return lowerLeft.add( upperRight).divide( 2);
} 
public Point getCenter()
   {
   return lowerLeft.add( upperRight).divide( 2);
   } 
Doc 11, Assignment 2 Comments Slide # 3

Names

public class Rectangle {
   Point p1;
   Point p2;
   Point p3;
   Point p4;
   Blah;
}

public class Rectangle {
   Point origin;      //Which origin?
   float width;
   float height;
   Blah
}

public class Rectangle {
   Point lowerLeftCorner;
   float width;
   float height;
   Blah
}

Doc 11, Assignment 2 Comments Slide # 4

public class Rectangle {
   public boolean containsRectangle( Rectangle ) { blah}
   public boolean containsPoint( Point ) {blah}
}

public class Rectangle {
   public boolean contains( Rectangle ) { blah}
   public boolean contains( Point ) {blah}
}

Doc 11, Assignment 2 Comments Slide # 5

public class Rectangle {
   public void setOrigin( Point origin ) {blah}
   public Point getPointOrigin( ) {blah}
} 

public class Rectangle {
   public void origin( Point origin ) {blah}
   public Point origin( ) {blah}
} 

public class Rectangle {
   public void setOrigin( Point origin ) {blah}
   public Point getOrigin( ) {blah}
} 

Doc 11, Assignment 2 Comments Slide # 6

Comments

// A Constructor
public Rectangle()
   {blah
   }

// Method: getCenter
// Operation: computes the center of the rectangle by adding the
//      lowerleft corner and the upper right corner and dividing by 2
// Returns: point that is the center of the rectangle
public Point getCenter()
   {
   return lowerLeft.add( upperRight).divide( 2);
   }
Doc 11, Assignment 2 Comments Slide # 7

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

Doc 11, Assignment 2 Comments Slide # 8

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 ' );
Doc 11, Assignment 2 Comments Slide # 9

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

Doc 11, Assignment 2 Comments Slide # 10

Kinds of Comments

• Repeat of the code

X := X + 1    /* add one to X
/* if allocation flag is zero */
if ( AllocFlag == 0 ) ...

• Explanation of how code works

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;

Doc 11, Assignment 2 Comments Slide # 11

• 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

Doc 11, Assignment 2 Comments Slide # 12

Keep Code simple

if ( a == true && b == true )
   return true
else
   return false

return ( a == true && b == true )

return a && b

Doc 11, Assignment 2 Comments Slide # 13

Asserts

assert( a == true )

assert( a )

assert( a == false )

assert( !a )

Testing

public class Rectangle {
   public boolean contains( Point origin ) {
      return true;
   }
} 

Inside

Outside

On border

Doc 11, Assignment 2 Comments Slide # 14

Try-catch

try
   {
   blah
   }
catch (Exception error)
   {
   System.out.println(" There was an error ");
   System.exit( 0 );
   }

Doc 11, Assignment 2 Comments Slide # 15

Points & Rectangles

Previous    visitors since 09-Oct-00    Next