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