Design Note #2 - Package Structure is Important

A package is a small piece of code focused on a single activity, e.g., it is cohesive. In order to test and extend packages, designers need to understand their operations, and so spend a lot of time reading their text. To support this study, we will structure our packages so that:
  1. Most C++ packages consist of two files, a header file with extension .h, and an implementation file with an extension .cpp. The header file contains public declarations of its services with class and global function declarations. The implementation file contains definitions of its declared services and private helper functions.
  2. The header is wrapped by preprocessor statements that prevent the header from being compiled multiple times during compilation of an implementation file.
  3. Each header has a block of comments at the top we refer to as manual information. That contains a prologue briefly summarizing package operation, operating environment, and identifying the author. After the prologue comes manual information details that describe, in a paragraph or two, package operations, followed by a description of the package's public interface.
  4. Manual information is followed by a block of comments called maintenance information. That contains the package revision history and instructions for building the package.
  5. Manual and Maintenance comments are followed by public declarations of the packages services. These should be simple and disclose the operations of the package without divulging its implementation.
  6. The implementation file begins with a prologue that is almost identical to that of the header, followed by a set of include statements for the header files of packages on which the implementation depends.
  7. That is followed by implementation of each of the package's member and global functions. Each function is preceeded by a single line comment that describes the function's responsibility, usually in four or five words.
  8. Finally, we append a main function that serves as a construction test for the package. This function is bracketed with preprocessor statements that allow us to choose whether to compile the test or not. We compile during construction testing, but disable that when the package is used as a part of a larger subsystem.
image file not found

C++ Package Structure

Example:

The tokenizer package (Tokenizer.h and Tokenizer.cpp) from the Parser Demo is a good example of a well structured package.

Conclusions for: Package Structure is Important!

A published package contains:
  1. Header file with: preprocessor compilation guards, prologue, manual info, maintenance info, and service declarations.
  2. Implementation file with: prologue, include statements, service implementation, and construction test stub with a compilation switch.
All of the reusable modules provided for your use in our website follow this format, as your submitted code must, as well. Demonstration code, intended to illustrate some idea, but not intended for reuse will follow a much simpler format.