Function Headings
This style concerns the comments, and so is not essential to compilation.
However, it helps readability of code written by a number of people.
Some of these conventions may be arbitrary, but are none the less
useful for that.
Format
See a sample procedure heading . Note:-
- White space of two lines separating functions.
- The identifier of the function right-justified to make it easy to
find when flicking through a listing
- The separate definitions for standard and old C.
- The macros PUBLIC and PRIVATE (in HTUtils.h ) expand to null and to
"static" respectively. They show that one has thought about whether
visibility is required outside the module, and they get over the overloading
of the keyword "static" in C. Use one or the other. (Use for top level
variables too).
Entry and exit condidtions
It is most important to document the function as seen by the rest
of the world (especially the caller). The most important aspects of
the appearance of the function to the caller are the pre- and post-conditions.
The pre conditions include the value of the parameters and structures
they point to. Both include any requirements on or changes to global
data, the screen, disk files, etc.
_________________________________________________________________
Tim BL