UMBC CMSC 202, Computer Science II, Spring 1999, Sections 0101, 0102, 0103, 0104

Project Organization

File Organization

The organization and structure of the files for a C++ program is important. Poorly organized files make code maintenance and debugging difficult. Here are the rules for file organization for projects:

Each class is to be defined in a header file named after the class and with a .H suffix. For example, class Foo would be defined in the file Foo.H.
Every such header file (with a .H suffix) is to be guarded using the
```
  #ifndef FOO_H
  #define FOO_H
        .
        .
  #endif
```
style. This style is used to avoid multiple includes of the header.
With one small exception, no method is to be implemented in a header file. Implementation belongs in the matching implementation (.C) file. The one exception: an accessor or a mutator method for a data member may be done inline and defined in the header file, outside the class definition.
Each class is to be implemented in its own implementation file named after the class and with a .C suffix. For example, the Foo class would be implemented in the file Foo.C. Note that each class has two associated files -- the definition or header file (.H) and the implementation file (.C). Exception: a pure abstract class will have just the header file.
The main function is to be in its own file, named after the project and with a .C suffix. For example, the main function for project 3 would be in the file Proj3.C.
The executable for a project is to be named after the project. For example, the executable for project 3 would be in the Proj3 file.

Documentation

Every file is to be headed by comments giving the name of the file, your name, the creation and current dates, and a brief description of the file's contents.

The header file for a class presents the public interface for the class. We adopt the convention that class documentation is done in the header file. Implementation files may be documented also, but this is documentation for the programmer, not for the class user.

For an example of header file documentation, see the sample header below. You are encouraged to adopt this sample style. If you prefer your own style, that's ok, but it must meet the specifications laid out here.

Documentation of a class is to include the following information:

At the start of the definition, describe the class, the author (you), and the current version (a date).
At the start of each method describe
- The purpose of the method.
- The meaning of each parameter.
- Any pre-conditions.
- What is returned.
Data fields need not be documented since they are always private. You may document a data field if necessary for clarity.

Style

There is no universally-accepted coding standard for C++ programs. When you get that super high-paying job after graduation, you will most likely have to work to some coding standard. Most standards are arbitrary, but serve the important function of making your code more readable for others following the standard. Standards can also help in bug detection. Standards are good, but there is no one good standard.

For projects in this class, use the following coding standard:

Only one private, protected and public section in a class definition. private precedes protected precedes public.

Every data member of a class must be private.

Avoid global variables. You may use const variables globally - nothing else.

No macros. Use const variables for constants.

No inline functions except accessors/mutators for data members. Define inline functions in the class header file, not in the implementation file.

If a class has any constructor, provide a default constructor.

If a class has any dynamically-allocated members, provide a suitable destructor.

If a class has any virtual methods, provide a virtual destructor.

Naming conventions:

Constants in all caps. Example:
const int MAXSIZE
Class names capitalized. Join multiple words by capitalizing each one. Example:
class DoubleLinkNode
Function names capitalized. Example:
void SetSize(int)
Class data members underscored and lower case. Example:
int _length
Ordinary variables and parameters lower case. Join multiple words with underscores or mixed upper/lower case (but begin with lower case). Examples:
int growth_rate
int growthRate

Use a consistent style of indentation and placement of curly braces.

Makefiles

Every project must be submitted with an associated makefile. The makefile is to be named either Makefile or makefile, your choice.

The grader will compile your submitted project by typing 'make,' so your makefile must correctly make your project. This includes correct naming of the executable. See below for an example makefile. This example can be easily modified for each project; change the PROJ and SOURCES definitions and make the appropriate changes in the targets and commands.

The example makefile can be used to obtain a nice-looking printout of your code. Just type make print and a Postscript file will be produced, ready for printing on any Postscript printer.

The makefile can also be used to submit your project. As long as you have SOURCES correctly defined, it will submit all the required files. Just type make submit to submit your project.

Remember that the command lines following the target line are indented by the TAB character, not by spaces.

Example Makefile

#  Makefile
#  CMSC-202  Spring 1999    Project 1
#  Alan Baumgarten
#  Created: 26 January 1999
#  Current: 26 January 1999
#

PROJ    = Proj1
CC      = CC
CCFLAGS = -g -n32

SOURCES = \
$(PROJ).C \
PrintJob.H \
PrintJob.C \
PrintQueue.H \
PrintQueue.C \
Printer.H \
Printer.C

OBJECTS = \
PrintJob.o \
PrintQueue.o \
Printer.o

SUBMITCLASS  = cs202-01

PRINTPGM   = /usr/lib/print/lptops
PRINTFLAGS = -G -U -H -M2 -O0.4pt
PRINTFILE  = $(PROJ).ps

$(PROJ): $(PROJ).C $(OBJECTS)
	$(CC) $(CCFLAGS) -o $(PROJ) $(PROJ).C $(OBJECTS)

PrintJob.o: PrintJob.C PrintJob.H
	$(CC) $(CCFLAGS) -c PrintJob.C

PrintQueue.o: PrintQueue.C PrintQueue.H PrintJob.H
	$(CC) $(CCFLAGS) -c PrintQueue.C

Printer.o: Printer.C Printer.H
	$(CC) $(CCFLAGS) -c Printer.C

print: $(SOURCES)
	- $(PRINTPGM) $(PRINTFLAGS) $(SOURCES) Makefile > $(PRINTFILE)

submit:
	submit $(SUBMITCLASS) $(PROJ) $(SOURCES) Makefile

clean:
	- rm -f *~

cleaner:
	- make clean; rm -f *.o

cleanest:
	- make cleaner; rm -f $(PROJ)

Sample Header File

/*
   PrintQueue.H
   PrintQueue class header file
   Project 1, CMSC 202, Section 101, Spring 1999
   Alan Baumgarten
   Created:  21 January 1999
   Current:  26 January 1999
*/

#ifndef PRINTQUEUE_H
#define PRINTQUEUE_H
 
/*
   This class simulates a queue of print jobs.
   There is no limit to the number of jobs in
   the queue.
   Author:  Alan Baumgarten
   Version: 26 January 1999
*/

class PrintQueue {
private:
    char      _name[21];
    PrintJob* _head;
    PrintJob* _tail;
public:
    //  Default constructor.  Name is "Unnamed"
    PrintQueue();

    //  Construct empty PrintQueue with specified name
    //  Param queue_name:  Name of the queue (20 chars max.)
    PrintQueue (char* queueName);	

    //  Add a job to the queue
    //  Param job_ptr:  Pointer to the PrintJob
    //                 to be added
    void Enqueue (PrintJob* job_ptr);

    //  Remove a job from the queue
    //  Returns:  Pointer to first job in queue
    //  Pre-condition:  The queue must not be empty
    PrintJob* Dequeue ();

    //  Check to see if queue is empty
    //  Returns:  True if empty, false if not
    int IsEmpty();
};

#endif