David L. Paktor — Coding Templates

These Template files will help you to generate bug-free code that will be easier to verify, easier to maintain, and, yes, will get to market faster.

The time spent filling in the comments is more than made-up for by the speed of coding, verifying and not having to fix errors after QA.

To say nothing of the cost savings of not having errors in the field!

Commenting your code is not only a convenience to yourself while developing, it is also a courtesy to — and often a necessity for:

Those who will use and maintain your code after you have delivered it or have moved on.

Who might very well turn out to be:
Yourself a while down the road. (You weren't really planning on keeping all that stuff in your head all that time, were you?)

These Templates are arranged to cover two slightly different programming situations:

Where you are programming a straightforward, stand-alone application where all the source files will be visible to all the users and maintainers,
versus
Where you are presenting a set of libraries to a group of users who will only have access to the Application Program Interfaces (APIs) and are a separate group from the maintainers.

The difference is that:

In the "Std" version, all of the inputs and outputs of a function are listed with the body of the source, i.e., in the .c file,
while
In the "API" version, the externally-accessible inputs and outputs are listed with the header — i.e., the .h — file (which will be presented to the library users), whereas the body of the source (which will be available to the maintainers exclusively) lists only the hidden, or internally-accessible, inputs and outputs.

Instructions:

Download the templates, either individually or collectively from the and unpack:
- In the "Std" case, the only Function Prolog file you will need is the Std.c version.
- In the "API" case, you will need both the API.c and the API.h versions of the Function Prolog.
- The two Tplt files, .c and .h, are the same for both cases.
Customize the templates for your own use:
In the Header and Program Template files (HdrTplt.h and ProgModuleTplt.c):
1. The "Copyright? Hell no!" line only applies to the Templates themselves. Replace it with the copyright boilerplate that will apply to your project's code.
2. Likewise, replace the RCS keywords with the ones your organization prefers.
3. Add an "Updated by" line with your name (leaving room for the date & time). Or not, depending on your organization's preference.
In the "Function Prolog" files:
1. Add any classes of Inputs and Outputs, specific to your project, that are not already included. The important thing is to have a consistent location where they can be found, or, if not applicable, can be readily recognized as absent.
  
  An example of this can be found in the module, which uses a special internal (static) data-structure called the Control-Stack to pass data among its functions. The prolog of each function that uses it mentions it in the same place. (This is also true of the FCode Output buffer).
These will become your Master-Copies of the Template files. Keep them in a handy but protected place.
Using the Templates:
1. Don't be daunted! You don't have to fill in every line or section.
2. Copy the appropriate Tplt file to your intended file name. Write your brief synopsis in the first block.
3. Fill in other sections as appropriate, and remove section blocks that will not apply. If you make a mistake, don't worry; you can always back-fill from your Master-Copy.
4. For each function you are about to define, bring in a copy of the "Function Prolog" file. Fill in sections that apply, remove those that don't.
5. Keep the Function Synopsis short. That will help you keep your functions modular.
6. You will find that you are creating a Design Specification. Once you've completed it, your coding will go much easier. No guess-work. Just straight fill-in-the-lines.
7. Verification becomes a breeze.
8. And at the end, you've left a trail for the next programmer, or yourself…

Enjoy!