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:


Documentation

Every file is to be headed by comments giving the name of the file, your name, your section, your student ID, your GL email address, the creation and current dates, and a brief description of the file's contents. See the sample header file below for an example.

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 class 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:


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:


Makefiles

Every project must be submitted with an associated makefile. The makefile is to be named either Makefile or makefile, your choice. No other names are acceptable for your makefile.

The grading script will compile your submitted project by using your makefile, so your makefile must correctly make your project. This includes correct naming of the executable. A sample makefile for Project 1 is provided:

/afs/umbc.edu/users/e/d/edelman/pub/CMSC-341/Proj1/Makefile
It is pretty much ready to use for Project 1 and can be easily modified for other projects. Copy it to your directory and make any necessary changes. In some cases, the copy process converts the TAB characters to spaces. The makefile requires the TAB characters. If they were converted to spaces, change them back to TABs.

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. Sometimes the copying process converts TAB to spaces. Check your copy to be sure you have tabs.

A number of tutorials on makefiles are available. One is the UCS tutorial. Another is an excerpt from the GNU tutorial. Links to them are on the "Projects" page of the course web page. You can download a nice tutorial on Unix Programming Tools from the Stanford CS Library at http://cslibrary.stanford.edu/107/.


Sample Header File

Note: this header file is only a sample. It is not really usable in Project 1. Use it as a model of a well documented and correctly organized header file.
/* 
   Array.H
   CMSC-341  Fall 2000 Project 1
   Array ADT 
   Penny Rheingans, Section 4, 999-99-9999, rheingan
   Created:  1 September 2000
   Current:  8 September 2000
*/

#ifndef ARRAY_H
#define ARRAY_H

template <class T> class Array; // forward declaration

#include <iostream.h>

/*
  Improved array that allows dynamic resizing, range checking, and
  assignment to another Array.  An Array "knows" its own size.
  Author: Penny Rheingans
  Version: 8 September 2000
*/
template <class T>
class Array
{
public:
  // Default constructor.  Array size is zero.
  Array();      

  // Construct new Array of size sz, elements unspecified.
  // Param sz: the size of this Array.
  // Precondition: sz > 0.  If sz <= 0, Array size will be
  // taken as zero.
  Array(int sz);

  // Construct new Array of size sz_bi with initial
  // elements from bi_aray (a built-in array of size sz_bi)
  // Param bi_aray: a built-in array from which to draw the
  //    initial elements of this Array
  // Param sz_bi: the size of bi_aray
  // Precondition: bi_aray must really be of size sz_bi.  If
  // sz_bi <= 0, an empty Array is constructed.  If sz_bi 
  // exceeds the actual size of bi_aray, errors may occur due
  // to array access boundary violations.  If sz_bi is less than
  // the actual size of bi_aray, initialization of the Array
  // will be incomplete.
  Array(T* bi_aray, int sz_bi);

  // Copy constructor
  // Param arr: the Array to copy
  Array(const Array<T>& arr);

  // Destructor
  ~Array();

  // Accessor for size of this Array.
  // Return: the size of this Array.
  int getSize() const;

  // Increase this Array's size.
  // Param delta:  the amount by which to increase this 
  //   Array's size
  // Pre-condition: delta greater than or equal to zero. This
  // is enforced by an assertion.
  void grow(int delta);

  // Decrease this Array's size.
  // Elements are removed from the right (elements from
  // A[size - delta] through A[size - 1] are lost).
  // Param delta: the amount by which to decrease this 
  //   Array's size.
  // Pre-condition: delta greater than or equal to zero and
  //      no greater than present size of this Array. This is
  // enforced by an assertion.
  void shrink(int delta);

  // Assignment operator
  // Assign ar to this Array
  // Param: arr is the Array to assign (the rvalue)
  // Return: this Array after modification.
  Array<T>& operator= ( Array<T> & arr);


  // Index operator.  Retrieve element at the specified index.
  // Param: indx is the index 
  // Return: the element at index in this Array.
  // Pre-condition: 0 <= indx < size.  This is enforced by
  //    an assertion.
  const T & operator[] (int indx) const;

  // Output operator
  // Param: os the stream to which to write arr
  // Param: arr is the Array to write
  // Return: os
  friend ostream& operator<< (ostream& os, const Array<T>& arr);
private:
  int _size;
  T* _array;
};

// for g++ templates, #include the .C file
#include "Array.C"


#endif