# References

Various student papers

Code Complete , Steve McConnell, Microsoft Press, 1993, chapters 9 and 19

`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
```
Indentation, White space
```
```
Use white space to make program readable

Use indentation to show the program structure

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

verses

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

`Doc 9, Names & Comments Slide # 5`

# Names

Example 1
```String s1;
String s2;
String s3;
int index1;
int index2;
```
verses

```String  escapeChar;
String  charsToEscape;
String  unescapedString;
```
Example 2
```
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() {  }
```
verses
```Node previous;
public float average() { stuff }
int length;
float average;
String escapeChar;
Doc 9, Names & Comments Slide # 6
```
Example 3
```
public  String  escape( String text)  {
StringBuffer tmp  =  new StringBuffer();
```
verses

```public  String  escape( String unescapedText)  {
StringBuffer escapedText  =  new StringBuffer();
```
Only Possible Use of Temp

```int temp;
temp = a;
a = b;
b = temp;
//temp not used after this
```
A Better Way?

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

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

verses

```while ( ! endOfFile )
{
//blah
}
```

Example 5

How long will these be meaningful?

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

"Finding good names is the hardest part of OO Programming"

"Names should fully and accurately describe the entity the variable represents"

What role does the variable play in the program?

 Data Structure Role, function InputRec EmployeeData BitFlag PrinterReady Queue buffer

Some Examples of Names, Good and Bad

 TrainVelocity Velt, V, X, Train CurrentDate CD, Current, C, X, Date LinesPerPage LPP, Lines, L, X
`Doc 9, Names & Comments Slide # 9`

```//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
```

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 ' );
Doc 9, Names & Comments Slide # 11
```
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
`Doc 9, Names & Comments Slide # 12`

• 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

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

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

Avoid abbreviations

What verses Why

What

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

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

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

## 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}
}
```

Copyright © 1999 SDSU & Roger Whitney, 5500 Campanile Drive, San Diego, CA 92182-7700 USA.