Coding / Commentation
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
- Where you are programming a straightforward,
stand-alone application where all the source files will be
visible to all the users and maintainers,
- 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
- 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.
Download the templates, either individually or collectively from the
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.
the templates for your own use:
Header and Program Template files
(HdrTplt.h and ProgModuleTplt.c):
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.
Likewise, replace the RCS keywords with the ones
your organization prefers.
Add an "Updated by" line with your name (leaving room for the
date & time). Or not, depending on your organization's
In the "Function Prolog" files:
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:
Don't be daunted! You don't have to fill in every line or section.
Copy the appropriate Tplt file to your intended
file name. Write your brief synopsis in the first block.
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.
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.
Keep the Function Synopsis short. That will help you keep
your functions modular.
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.
Verification becomes a breeze.
And at the end, you've left a trail for the next programmer,