CS Project Options
Instructor: Pradip Peter Dey,
OPTION-3:
Using software engineering principles, develop a program to insert comments into a C++ or Java program. The central idea of automatic comment generation is described below.
ABSTRACT
Currently there is no software tool that can automatically generate formatted comments into a program. We will develop a tool that will automatically generate formatted comments into a program. Once the comments are generated, any documentation tool such as javadoc then can utilize the comments in order to generate proper documentation for the program.
INTRODUCTION
Programmers are expected to write programs with a lot of comments. However, programmers can concentrate on writing programs if someone else can generate appropriate comments for their programs. As far as we know, there is no software tool that can automatically generate formatted comments into a program. The goal of this research is to develop a tool that will automatically generate formatted comments into a program. Once the comments are generated, a documentation tool such as javadoc then can utilize the comments in order to generate proper documentation for the program.
Consider the following Java program that computes the average bill size for a person’s shopping bills.
import java.io.*;
import java.util.Vector;
import javax.swing.*;
public class Expense
{
private static int count = 0;
private static double billSize,
total = 0;
private static double average = 0;
private static Vector expenseVect = new Vector();
public static void main(String args[])
{
String SbillSize;
SbillSize = JOptionPane.showInputDialog(
"This program computes average bill size. Please enter " +
“ a bill size; enter –1 to exit. ” );
billSize = Double.parseDouble(SbillSize);
while (billSize > 0)
{
expenseVect.addElement(new Double(billSize));
count++;
total += billSize;
SbillSize = JOptionPane.showInputDialog(
"Please enter a bill size; " +
“ enter –1 to exit. ” );
billSize = Double.parseDouble(SbillSize);
}
if ( count > 0)
average = total / (double) count;
displayResults();
System.exit( 0 );
}
public static void displayResults()
{ String St = “ “;
for (int i=0; i < expenseVect.size(); i++)
{ St += “ “;
St += (expenseVect.elementAt(i));
}
JOptionPane.showMessageDialog( null,
"\n The Total Number of bills is: " + count +
“\n The Total Expense is: " + total +
“\n The Average Bill Size: “ + average +
“\n The Expenses are: “ + St );
}
}
Although the above Java program is not difficult to understand, it does not have any comments. Programs such as this are considered to be poor not because of their technical quality but for their lack of comments. Usually, a programmer has to manually insert comments into the program like this. Programmers may or may not like to manually generate comments. But, the comments are necessary for several reasons such as readability and maintainability of the programs. After the comments are inserted the Java program given above will look like the following:
/**
* File : Expense.java
* Author : P. Peter Dey
* Date : 11-08-00
* Language : Java (jdk1.2.2)
*/
/** IMPORTED PROGRAM LIBRARIES */
import java.io.*; /** for general input output */
import java.util.Vector; /** for Vector data structure */
import javax.swing.*;
/**
* This class computes the total expense, the total number of bills
* and the average bill size. Each expense is input by the user one
* at time in response to a prompt. A negative integer or 0 is entered
* to indicate the end of input session. It also prints out the
* total number of bills, the total expense and the average bill
* size.
* @author: Pradip Peter Dey, National University
*/
public class Expense
{
private static int count = 0; /** total count of bills */
private static double billSize, /** size of a bill (input) */
total = 0; /** total expense (computed) */
private static double average = 0; /** average bill size (computed) */
private static Vector expenseVect = new Vector();
/** storage for bill sizes */
/**
* The main() method. It gets each Bill Size from the user
* interactively and computes the
* Total amount of all bills and the average bill size
*/
public static void main(String args[])
{
String SbillSize; /** String variables for input */
SbillSize = JOptionPane.showInputDialog(
"This program computes average bill size. Please enter " +
“ a bill size; enter –1 to exit. ” ); /** Input is read as a string */
/** and assigned to SbillSize */
billSize = Double.parseDouble(SbillSize); /** which is converted to Double */
while (billSize > 0)
{
expenseVect.addElement(new Double(billSize));
count++;
total += billSize;
SbillSize = JOptionPane.showInputDialog(
"Please enter a bill size; " +
“ enter –1 to exit. ” ); /** Input is read as a string */
/** and assigned to SbillSize */
billSize = Double.parseDouble(SbillSize); /* String is converted */
}
if ( count > 0)
average = total / (double) count;
displayResults();
System.exit( 0 );
}
/**
* This method displays the total number of bills,
* the total expense and the and the average
* bill size. It does not return any value.
*
* Pre: count, expenseVect, total and average are assigned
* proper values
* Post: count, elements of expenseVect, tatal and average are
* displayed with identifying texts.
*
*/
public static void displayResults()
{ String St = “ “;
for (int i=0; i < expenseVect.size(); i++)
{ St += “ “;
St += (expenseVect.elementAt(i));
}
JOptionPane.showMessageDialog( null, /** Output is displayed */
"\n The Total Number of bills is: " + count +
“\n The Total Expense is: " + total +
“\n The Average Bill Size: “ + average +
“\n The Expenses are: “ + St );
}
} /** End of Expense */
Comments inserted into a program are called program comments. Program comments should have several requirements: (1) comments should be meaningful although most comments are in incomplete sentences or sentence fragments; (2) comments should be inserted into appropriate places, (3) comments are formatted for documentation tools such as javadoc, (4) comments are also formatted for readability.