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 its own header file. The file extension must be .H or .h It's a good idea, but not required, to name this file after the class. For example, class Foo would be defined in a file named Foo.H or Foo.h
Every such header file 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.
No method is to be implemented in a header file. Implementation belongs in the matching implementation file.
Each class is to be implemented in its own implementation file. The file extension must be .C or .CC or .cpp It's a good idea but not required to name this file after the class. For example, the Foo class would be implemented in a file named Foo.C or Foo.CC or Foo.cpp.

Note that each class has two associated files -- the definition or header file and the implementation file.
A header file is to be included in a given file if and only if the header defines an entity referred to in the given file. Do include the header if it defines an entity referred to. Do not include it otherwise. For example, suppose Foo.h refers to an ostream entity and a string entity. Then, definitely do include iostream.h and mystring.h in Foo.h. Now, suppose the implementation file Foo.C refers to an ostream entity, but not a string entity. Then Foo.C should include Foo.h and iostream.h, but not mystring.h. Note that iostream.h is included even though its inclusion is also caused by including Foo.h. Guarded header files keep this from causing multiple definition and your code becomes cleaner and more readable.
The main function is to be in its own file. The file extension must be .C, .CC, or .cpp It's a good idea, but not required to name the file after the project. For example, the main function for project 3 would be in a file named Proj3.C, Proj3.CC or Proj3.cpp
The executable for a project must be named after the project. For example, the executable for project 3 must be in the Proj3 file. This is very important because the grading script will look for that file to run your program. The script will not run a.out or any other executable. The executable name is controlled by your makefile - get it right. Do not submit your executable, the grading script will construct it by using your makefile.

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:

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.
- Any side effects.
- The meaning of 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:

No more than one private, protected or public section in a class definition.
Every data member of a class must be private.
Avoid global or file-scope variables. You may use const variables globally - nothing else.
Avoid macros (#define) for constants. Use const variables for constants.
Every class must define a default constructor, even if it does nothing.
Every class must define a destructor, even if it does nothing.
Every class must define an appropriate copy constructor.
Every class must define an appropriate assignment operator.
If a class has any virtual methods, provide a virtual destructor.
If an accessor is provided for a data member, it must be a const method. Example:
```
int getSize() const
```
If a mutator is provided for a data member, it must return void. Example:
```
void setSize(int newsize)
```
Here are some suggested naming conventions. The important thing is that your naming is consistent. Following these conventions will help consistency. If you don't like these, adopt your own, but be consistent.
- Constants all upper-case. Example:
  const int MAXSIZE
- Class names begin with an upper-case letter. Join multiple words by capitalizing each one. Examples:
  class DoubleLinkNode
  class Matrix
- The names of functions, methods, ordinary variables, and parameters begin with a lower case letter. Join multiple words by capitalizing each one. Examples:
```
void setSize(int)
int inverse(int)
Matrix mat
int arraySize
```
- Class data members underscored and lower case. Example:
  int _length. Remember, all class data members must be private.

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