Code Inspection Report

Code Inspection Report

November 24,2001

Team Discovery

Table of Contents

1.0 Introduction3

1.1 Significant Changes Since Prototype Demo3

1.1.1 Revisions to the SRS 3

1.1.2 Revisions to the SDD3

1.2 Coding and Commenting Conventions3

1.3 The Code Inspection Process4

1.3.1 Process4

1.3.2 General Impressions and Quality4

1.3.3 Meetings5

2.0 The Code Inspection6

2.1 Omitted Modules6
2.2 BatchLogFile6
2.3 Menu6
2.4 CustomerListFile7
2.5 FormLetterFile7
2.6 FormLetter8
2.7 CustomerList9
2.8 CustomerRecord9
2.9 FormLetterGenerator10

3.0 Defects10

Appendix A. Coding Conventions12
Appendix B. Glossary13
Appendix C. Code13

1.0 Introduction

1.1 Significant Changes Since Prototype Demo

The major changes revolve around completion of coding and minor revisions to some of the class definitions. Since the prototype, all methods and classes have been fully coded. In the prototype, methods were called as placeholders, describing their purpose rather than fulfilling it. They have been replaced by their operational counterparts. In addition to that, we have changed the order in which some of the data files are loaded to follow a more logical flow of data. The changes to the data flow are covered completely in the next two sections.

1.1.1 Revisions to the SRS

There have been no changes to the SRS.

1.1.2 Revisions to the SDD

Changes made to the SDD are in the manner in which the data is processed, when one of the data files is loaded, and exception classes were added to several of the classes. The customer data file is not loaded until after the client decides between commercial or residential customers. This is done so that the customer database presented to the user does not include customers that should otherwise not receive the form letter. The second major revision is in the interaction between the FormLetter class, and CustomerList class with respect to populating tags with customer data from individual customer records. Instead of individual fields being passed through the FormLetterGenerator, entire customer records are passed through. The last revision was the addition of exception handling in cases of fatal errors. Instead of shutting down the entire program in such cases, exceptions are now thrown to handle these.

1.2 Coding and Commenting Conventions

Conventions for coding mainly revolved around naming of classes, their methods, and their data members. Primarily, all names consisting of more than one word will have all subsequent words capitalized. For classes we defined and for their methods, we capitalized the first letter of the name. The first letter of the names of data members is lowercase. Data members that are pointers are preceded by a ‘p_’, and enumerated types have a trailing ‘_t’ attached. We have chosen this coding style to help with modularity and readability

Commenting conventions base most of our commenting in the implementation files as opposed to the definition files. Comments are placed before each method, and explain input, output, and side effects, as well as a brief description of the purpose. Furthermore, within any sections of code that are not readily straightforward, we have included comments as an explanation. We have chosen to comment in this manner for readability, and for white box testing, giving the advantage of fully understanding what the correct outcome should be.

1.3 The Code Inspection Process

1.3.1 Process

The process our team followed was a top down analysis of the code, starting from the most complex class, followed by it’s immediate components, and finally down to the factory files that create them. We proceeded in this manner because it helped to explain some methods of lower level subsystems whose purpose might have otherwise seemed unclear. First the header files were looked over, and the methods explained, then the implementation files were reviewed, and their logical flow was examined.

1.3.2 General Impressions and Quality

Overall, our inspection of the code led to our uncovering a few possible defects in our design and a more open discussion on how we could fix them. The inspection gave the entire team a good view of the details that otherwise were not known.

The quality of the code before the inspection was quite good; however, there are almost always errors, and this step in the software life cycle helped to insure attention to some of the more intricate details. After we made repairs to the code, we eliminated a number of possible segmentation faults due to uninitialized subclasses.

The best module is by far the CustomerRecord class, because it is a simple container class, and data is set and accessed in a limited number of ways. The class with the most likelihood of errors still existing is the FormLetterGenerator class, as it is the main controlling body of the program, and problems in the order or manner in which it’s members are set and utilized could have the most catastrophic effects on the performance of the product.

1.3.3 Meetings

During both meetings, Drew acted as the presenter, with help from Michael at times. Michael took notes on the inspection, as well as reviewed the code. Jessica and Andy helped reviewed the code, offering suggestions for changes in methods, and asked questions regarding the purposes of certain parts.

First Meeting

Date: Nov 12,2001

Location: UMBC Library Basement

Time: 4 pm to 5:15 pm

Attendance:

Code Covered: FormLetterGenerator

Second Meeting

Date: Nov 19,2001

Location: XXXXX’s Apartment

Time: 8:30pm to 11:45pm

Attendance: All team members attended.

Code Covered: FormLetterGenerator

CustomerRecord

CustomerList

FormLetter

FormLetterFile

CustomerListFile

Third Meeting

Date: Nov 26, 2001

Location: Lobby of the Umbc Library.

Time: 8:30pm to 10:00pm

Attendance: All team members attended.

Code Covered: Menu

BatchLogFile

2.0 The Code Inspection

2.1 Omitted Modules

A number of modules where omitted from the code inspection for various reasons. Utility classes were omitted because they were written prior to the project, and were fully tested.

Utility Classes Omitted

genericDefs

string

vector

EzlinkedList

Other Classes Omitted

Printer

This module was omitted since at the time of the inspection, we were exploring a number of ways to print the form letters, but we had not finalized any techniques, so it contained only empty definitions.

2.2 BatchLogFile

Description

This module is contained inside of the ‘ViewSavedJob’ and ‘PrintLetters’ methods inside of the FormLetterGenerator object, saving batch jobs, and loading previously saved batches.

Comments and Coding Convention

Coding conventions were followed fully. There were no comments in the header file and minimal comments in the implementation file.

Error Handling

No error handling is done within this module. The modules that use this must send it correct data. It does not handle errors in the case of corruption of it’s own files.

Variations in Design

The module conforms to the design in the SDD.

2.3 Menu

Description

This module is used inside a number of the subsystems as a

utility to display menus.

Comments and Coding Convention

Coding conventions were followed fully. There were no comments in the header file and minimal comments in the implementation file.

Error Handling

No error handling is done within this module. The modules that use this must send it correct data.

Variations in Design

The module conforms to the design in the SDD.

2.4 CustomerListFile

Description

This module is invoked from within the CustomerList class. It builds the list of customers using the CustomerRecord container class.

Comments and Coding Convention

Coding conventions were followed fully. There were no comments in the header file and minimal comments in the implementation file.

Error Handling

This module throws an exception in the case that the file containing the customer list is not valid. The modules that use this must send it correct data.

Variations in Design

In the original design, CustomerListFile was a separate type, and in the new implementation, we have made it a friend to CustomerList. The design was altered to ease with creation of the CustomerList.

2.5 FormLetterFile

Description

This module is a factory class, similar to the CustomerListFile. It is contained inside of the FormLetter class. This builds the form letter pointed to by the FormLetterGenerator class.

Comments and Coding Convention

Coding conventions were followed fully. There were no comments in the header file and minimal comments in the implementation file.

Error Handling

This module throws an exception in the case that the file containing the form letter is not valid or does not exist. The modules that use this must send it correct data.

Variations in Design

In the original design, FormLetterFile was a separate type, and in the new implementation, we have made it a friend to the FormLetter class. The design was altered to ease with creation of the letter.

2.6 FormLetter

Description

This module is contained inside of the FormLetterGenerator class. It holds the form letter and is contains the functionality to generate each form letter given a particular type of customer record. An exception class, FormLetterException, is also defined here to handle errors.

Comments and Coding Convention

Coding conventions were followed fully. There were no comments in the header file and minimal comments in the implementation file.

Error Handling

The module returns exceptions from the FormLetterFile class inside of the constructor. It also returns exceptions in cases where there is an invalid tag within the form letter. It does not handle errors in the case of corruption of it’s own files. The modules that use this must send it correct data.

Variations in Design

FormLetterFile was made a friend class for the reason listed in 2.5 above. An exception class was also added to facilitate handling otherwise potentially fatal errors. In the original design, the error would cause the product to exit, whereas now it simply returns to the main menu after generating an error message.

2.7 CustomerList

Description

This module is contained within the FormLetterGenerator class and contains an array of CustomerRecords. It is generated by the CustomerListFile class, which was made a friend class to this after code inspection. It also contains the user's choices for selection of customers, as well as methods to return the next customer record to be passed to the FormLetter class. An exception class, CustomerListException, was also added to handle errors.

Comments and Coding Convention

Coding conventions were followed fully. There were minimal comments in the header file and in the implementation file.

Error Handling

The module returns exceptions from the CustomerListFile in the constructor. It does not handle errors in the case of corruption of it’s own files. The modules that use this must send it correct data.

Variations in Design

CustomerListFile was made a friend class for the reason listed in 2.4 above. An exception class was also added to facilitate handling otherwise potentially fatal errors. In the original design, the error would cause the product to exit, whereas now it simply returns to the main menu after generating an error message.

2.8 CustomerRecord

Description

This module acts as a container for the customer record. It is generated inside of the ‘CreateCustomerList’ method in the CustomerListFile class. It contains methods to access information about each record, which is used by the FormLetter class.

Comments and Coding Convention

Coding conventions were followed fully. There were no comments in the header file or in the implementation file.

Error Handling

This module is quite simple and generates no errors. By the nature of the ‘strtok’ function and the string utility class, there is no possibility for errors.

Variations in Design

The module conforms to the design in the SDD.

2.9 FormLetterGenerator

Description

This module is the system module from where the user controls the flow of the program’s execution. It contains pointers to the CustomerList and the FormLetter classes, as well as an exception class, LetterGeneratorException, to handle errors. The methods contained within this class correspond to the various use cases listed in the SRS.

Comments and Coding Convention

Coding conventions were followed fully. There were minimal comments in the header file and in the implementation file.

Error Handling

This module handles output for all exceptions thrown in other modules. End user input errors are guarded against in the subsystems of this class.

Variations in Design

The LetterGeneratorException class was added to handle exceptions during execution of menu options. In the original design, fatal errors would cause the program to terminate, but in the amended design, they cause the program to return to the main menu after generating an error message.

3.0 Defects

3.1

Location: FormLetterGenerator

Description: Help option has not been implemented

Category: Completeness

Status: Not yet fixed

3.2

Location: FormLetterGenerator

Description: The customer list is not reset before program execution

begins.

Category: Other

Status: Fixed

3.2

Location: FormLetterGenerator

Description: The function to print the form letters does nothing

Category: Completeness

Status: Not Fixed Yet

3.3

Location: FormLetterGenerator

Description: Inside of ViewSavedBatch, if a CustomerList hasn’t been

loaded, then it will seg-fault.

Category: Other

Status: Fixed

3.4

Location: CustomerList

Description: Program will display all customers, regardless of whether

or not they are the intended recipients of the form letter.

Category: Correctness

Status: Fixed

3.5

Location: FormLetter

Description: Function to generate populated letter is not complete

Category: Completeness

Status: Not yet fixed

3.6

Location: FormLetterFile

Description: Does not properly handle newlines

Category: Correctness

Status: Not yet fixed

3.7

Location: FormLetterFile

Description: method for importing form letters ‘IsValid’ doesn’t

do anything.

Category: Completeness

Status: Fixed

3.8

Location: Menu

Description: Input stream is not flushed between inputs, resulting in

Input being handled incorrectly.

Category: Other

Status: Not yet fixed

3.9

Location: CustomerListFile

Description: No check is performed on the customer file to insure it is

Of the proper format.

Category: Completeness

Status: Not yet fixed

3.10

Location: BatchLogFile

Description: When the time stamp is placed in the batch_log.txt file,

if the minutes are in the single digit, it doesn’t display a

leading zero.

Category: Completeness

Status: Not Yet Fixed

3.11

Location: FormLetterFile

Description: The manner in which the form letter is read in ignores

formating character such as newline and tab.

Category: Correctness

Status: Fixed

Appendix A. Coding Conventions

Classes:

Name: MyClassName

The name of the class is capitalized, along with all of the words that make up the name, without spaces between them.

Methods: MethodName

The names of the methods are capitalized, along with all of the words that make up them, without spaces between them.

Data Members: classDataMember

The names of the data members begin lowercase, and each subsequent word in the name is capitalized, without spaces between them.

Variables:

Naming: someVariableName

The names of variables follow the same rules as data members of classes.

Pointers:

Naming: p_myPointerName

Pointer names follow the same rules as variable names, except they have a ‘p_’ placed on the beginning to designate them as pointers.

Enumerated Types:

Naming: myEnumeratedType_t

Enumerated types follow the same rules as pointers with the exception that they are followed by an ‘_t’ to designate them as enumerated. There is one exception to this rule, which is the user-defined type ‘BOOL.’ It is enumerated, but since it is commonly referred simply as ‘BOOL’ or ‘bool’, we have chosen to omit the trailing designator.

Appendix B. Glossary

1.1. SDD – Abbreviation for System Design Document, this document.

1.2. SRS – Abbreviation for System Requirements Specification.

1.3. Populate – to replace tags in the form letter which designate specific fields within a customer record

Appendix C. Code

BatchLogFile (Old)

#include "BatchLogFile.H"

#include "genericDefs.H"

#include <stdlib.h>

#include <stdio.h>

#include <string.h>

BatchLogFile::BatchLogFile()

{

}

BatchLogFile::BatchLogFile(String fname)

: filename(fname), numLogs(0)

{

ifstream inputFile(filename.c_str(), ios::in);

char buffer[256];

char *temp;

while (!inputFile.eof())

{

inputFile.getline(buffer, 255, '\n');

if ( strlen(buffer) > 10 ) // another legal log exists

{

// pull off the type

temp = strtok( buffer, ",");

types.add( strtol( temp, NULL, 10 ) );

// pull off filename

temp = strtok( NULL, ",");

filenames.add( String(temp) );

// pull off the number of customers

temp = strtok(NULL, ",");

numCustomers.add( strtol( temp, NULL, 10 ) );

// pull off the margin width

temp = strtok(NULL, ",");

marginWidths.add( strtol( temp, NULL, 10 ) );

// pull off the date

temp = strtok(NULL, ",");

dates.add( String(temp) );

// pull off the city options

inputFile.getline(buffer, 255, '\n');

cityOptions.add( String(buffer) );

// pull off the state options

inputFile.getline(buffer, 255, '\n');

stateOptions.add( String(buffer) );

// pull off the zipcode options

inputFile.getline(buffer, 255, '\n');

zipcodeOptions.add( String(buffer) );

numLogs++;

} // end if legal log

} // end while

}

BatchLogFile::~BatchLogFile()

{

}

int BatchLogFile::NumLogs(void)

{

return numLogs;

}

// title: (date type filename)

String BatchLogFile::GetLogTitle(int index)

{

String logTitle;

logTitle += dates[index];

logTitle += String(" ");

if (types[index] == COMMERCIAL)

logTitle += String("COMMERCIAL ");

else

logTitle += String("RESIDENTIAL ");

logTitle += filenames[index];

return logTitle;

}

/*

* log: (date

* type

* filename

* numCustomers

* marginWidth

* cities

* states

* zipcodes)

*/

String BatchLogFile::GetLog(int index)

{

String log;

char buffer[256];

char * temp;

// add date

log += String("date-time: ");

log += dates[index];

// add type