CS 535 Object-Oriented Programming & Design Spring Semester, 1999 Names & Comments
	Previous    Lecture Notes Index    Next     © 1999, All Rights Reserved, SDSU & Roger Whitney San Diego State University -- This page last updated 25-Feb-99

References
Meyer's Criteria for Evaluating for Modularity
Indentation, White space
Names
Comments

Kinds of Comments
Commenting Efficiently
Commenting Techniques
Commenting Data Declarations
Commenting Routines

References

Doc 9, Names & Comments Slide # 2

Meyer's Criteria for Evaluating for Modularity

• Decomposability
• Composability
• Understandability
• Continuity
• Protection

Doc 9, Names & Comments Slide # 3

Indentation, White space

public class Assgn1_Part1
{
   public static void main(String args[])
   {
            Console.println();
// Initialize strings
      DataString A=new DataString('A');      // This will prompt 
===>the user for a string.
      DataString B=new DataString('B');      // This will prompt 
===>the user for a string.
      DataString C=new DataString('C');      // This will prompt 
===>the user for a string.
      String D="";
      int i=0;
      do
      {
         {
            String a;
            String b;
            int j=0;
// Check each character of A
            do
            {
               a = A.Data.substring(i+j,i+j+1);
               b = B.Data.substring(j,j+1);
               j++;
            }
// If a letter matches, see if the whole string B is contained 
            while (a.toLowerCase().equals(b.toLowerCase())
               &&(j<B.Data.length()))
            if (a.toLowerCase().equals(b.toLowerCase())
               &&(j<B.Data.length()))
            {
// Place C into D
               D=D+C.Data;
               i+=j;
            }
            else
            {
// Place the letter from A into D
               D=D+A.Data.substring(i,i+1);
               i++;
            }
         }
      }
// Do until the end of A is too short to contain B
      while (i<=(A.Data.length()-B.Data.length()));
Doc 9, Names & Comments Slide # 4

while (a.toLowerCase().equals(b.toLowerCase())
   &&(j<B.Data.length()))
if (a.toLowerCase().equals(b.toLowerCase())
   &&(j<B.Data.length()))

while   (    ( a.toLowerCase().equals( b.toLowerCase() ) ) && 
            ( j<B.Data.length() ) 
         )
         if   (   ( a.toLowerCase().equals( b.toLowerCase() ) ) &&
               ( j<B.Data.length() )
            )
            {
               // Code deleted
            }

while   (    ( a.toLowerCase().equals( b.toLowerCase() ) ) && 
            ( j<B.Data.length() ) 
         )
         {
            // Code deleted
         }

Doc 9, Names & Comments Slide # 5

Names

String s1;
String s2;
String s3;
int index1;
int index2;

String  escapeChar;
String  charsToEscape;
String  unescapedString;

Node pre;
public float compute() { stuff }
int len;
float avrg;
float avrge;
String esc_char;
String string;
Node ptr;
String strTheString;
public void scan_string() {  }

Node previous;
public float average() { stuff }
int length;
float average;
String escapeChar;
Doc 9, Names & Comments Slide # 6

public  String  escape( String text)  {
   StringBuffer tmp  =  new StringBuffer();

public  String  escape( String unescapedText)  {
   StringBuffer escapedText  =  new StringBuffer();

int temp;
temp = a;
a = b;
b = temp;
//temp not used after this

int swapSpace;
swapSpace = a;
a = b;
b = swapSpace;
Doc 9, Names & Comments Slide # 7

boolean condition = true;
while ( condition )
   {
   //blah
   }

while ( ! endOfFile )
   {
   //blah
   }

class p1p1 { //blah }
class p1p2 { //blah }
class project1problem2 { //blah }
Doc 9, Names & Comments Slide # 8

Doc 9, Names & Comments Slide # 9

Comments

//Declare fields
String s1;   //escape character
String s2;   //special characters
String s3;   //input string
//Prompt user for escape character
s1 = Console.readLine( "Type an escape character" );
//Prompt user for special characters
s2 = Console.readLine( "Type an escape character" );
s2 = s1 + s2                  // add s1 to s2
class FooBar
   {
   //Constructor
   public FooBar();
Doc 9, Names & Comments Slide # 10

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 9, Names & Comments Slide # 11

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 9, Names & Comments Slide # 12

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 9, Names & Comments Slide # 13

• 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 9, Names & Comments Slide # 14

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 9, Names & Comments Slide # 15

Commenting Techniques

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

Doc 9, Names & Comments Slide # 16

/* 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 ) ...
Doc 9, Names & Comments Slide # 17

{ 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;
Doc 9, Names & Comments Slide # 18

{ 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;
Doc 9, Names & Comments Slide # 19

Commenting Data Declarations

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
Doc 9, Names & Comments Slide # 20

Commenting Routines

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

Previous    visitors since 25-Feb-99    Next