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