N P C C T B H P N

Note #2 - Package Structure Matters!

A package is a small piece of code that obeys the Single Responsibility Principle (SRP): it is focused on a single activity. 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:

C# packages consist of a single source file, an implementation file with an extension .cs. The file contains the definition of one or more classes (usually one) with public declarations and implementation of its services. Often there are private helper functions that a client need not be concerned with - they simply support the definition of public functions by extracting out some complex or repeated logic.
Each package file 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.
Manual information is followed by a block of comments called maintenance information. That contains the package revision history and instructions for building the package.
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.
The implementation with a set of using statements for all of the libraries on which the package depends.
That is followed by a class declaration that implementation of each of the package's member functions inline. Each function is preceeded by a single line comment that describes the function's responsibility, usually in four or five words.
Finally, we append a main function that serves as a construction test for the package. This function is bracketed with compilation constant 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.

File: Package_Name.cs

Manual Page goes here

Maintenance Page goes here

Declarations with inline implementations go here

#if(TEST_Package_Name)
static void Main(string[] args)
{
  // Test code goes here
}

C# Package Structure

Example:

The tokenizer package, Toker.cs, from the Parser Demo is a good example of a well structured package. Here is a sample output fragment from the tokenizer.

Conclusions for: Package Structure is Important!

A published package contains:

A package file with: prologue, manual info, maintenance info, service definitions, and construction test stub with a compilation switch.
Each of the member functions is preceeded by a single comment line that describes its responsibility in a few words.

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.